<!DOCTYPE html>
<html>
<head>
<meta charset="UTF-8">

<title>class IO - RDoc Documentation</title>


<script src="./js/navigation.js" defer></script>
<script src="./js/search.js" defer></script>
<script src="./js/search_index.js" defer></script>
<script src="./js/searcher.js" defer></script>
<script src="./js/darkfish.js" defer></script>

<script src="./js/jquery-3.2.0.min.js"></script>

<script src="./js/vue.min.js"></script>
<script src="./js/js.cookie.min.js"></script>

<link href="./css/fonts.css" rel="stylesheet">
<link id='rdoccss' href="./css/rdoc.css" rel="stylesheet">
<link href="./css/carbon17.css" rel="stylesheet">

<script type="text/javascript">
  var rdoc_rel_prefix = "./";
  var index_rel_prefix = "./";
  var darkModeCsseHref = "./css/rdoc-dm.css"
  var defaultModeCssHref = "./css/rdoc.css"
  // var cssDarkmode = Cookies.get('darkmode');
  
  if( Cookies.get("darkmode") == "true") {
	$('#rdoccss').attr("href", darkModeCsseHref);
}

//  https://cssdeck.com/blog/simple-jquery-stylesheet-switcher/

document.write('<style type="text/css">body{display:none}</style>');

</script>


</head>
<body id="top" role="document" class="class">
  <!-- this is class.html -->

  <div id='actionbar' >
    <div class='wrapper mdiv'>
      <ul class='grids g0'></ul>
    </div> 
    <!-- VERSION HEADER for 3.3.0-preview2 NOT FOUND -->
  </div> <!-- end action bar -->

  <div class='wrapper hdiv'>

    


    <nav id='vapp' role="navigation">
    <div id="project-navigation">
      <div id="home-section" role="region" title="Quick navigation" class="nav-section">
  <h2><a href="./index.html" rel="home">Home</a></h2>

  <div id="table-of-contents-navigation"  >
    <a href="./table_of_contents.html#pages">Pages</a>
    <a href="./table_of_contents.html#classes">Classes</a>
    <a href="./table_of_contents.html#methods">Methods</a>
  </div>
</div>

      <div id="search-section" role="search" class="project-section initially-hidden">
  <form action="#" method="get" accept-charset="utf-8">
    <div id="search-field-wrapper">
      <input id="search-field" role="combobox" aria-label="Search"
             aria-autocomplete="list" aria-controls="search-results"
             type="text" name="search" placeholder="Search" spellcheck="false"
             title="Type to search, Up and Down to navigate, Enter to load">
    </div>

    <ul id="search-results" aria-label="Search Results"
        aria-busy="false" aria-expanded="false"
        aria-atomic="false" class="initially-hidden"></ul>
  </form>
</div>

    </div>


    
<div class="nav-section">
  <h3>Table of Contents</h3>

  <ul class="link-list" role="directory">
    <li><a href="#class-IO-label-Extension+io-2Fconsole">Extension <code>io/console</code></a>
    <li><a href="#class-IO-label-Example+Files">Example Files</a>
    <li><a href="#class-IO-label-Open+Options">Open Options</a>
    <li><a href="#class-IO-label-Basic+IO">Basic IO</a>
    <li><a href="#class-IO-label-Position">Position</a>
    <li><a href="#class-IO-label-Open+and+Closed+Streams">Open and Closed Streams</a>
    <li><a href="#class-IO-label-End-of-Stream">End-of-Stream</a>
    <li><a href="#class-IO-label-Line+IO">Line IO</a>
    <li><a href="#class-IO-label-Line+Separator">Line Separator</a>
    <li><a href="#class-IO-label-Line+Limit">Line Limit</a>
    <li><a href="#class-IO-label-Line+Separator+and+Line+Limit">Line Separator and Line Limit</a>
    <li><a href="#class-IO-label-Line+Number">Line Number</a>
    <li><a href="#class-IO-label-Character+IO">Character IO</a>
    <li><a href="#class-IO-label-Byte+IO">Byte IO</a>
    <li><a href="#class-IO-label-Codepoint+IO">Codepoint IO</a>
    <li><a href="#class-IO-label-What-27s+Here">What’s Here</a>
    <li><a href="#class-IO-label-Creating">Creating</a>
    <li><a href="#class-IO-label-Reading">Reading</a>
    <li><a href="#class-IO-label-Writing">Writing</a>
    <li><a href="#class-IO-label-Positioning">Positioning</a>
    <li><a href="#class-IO-label-Iterating">Iterating</a>
    <li><a href="#class-IO-label-Settings">Settings</a>
    <li><a href="#class-IO-label-Querying">Querying</a>
    <li><a href="#class-IO-label-Buffering">Buffering</a>
    <li><a href="#class-IO-label-Low-Level+Access">Low-Level Access</a>
    <li><a href="#class-IO-label-Other">Other</a>
  </ul>
</div>


    <button id='toggleThing' @click="toggleNav()" >Show/hide navigation</button>
    <div :class="isOpen ? 'block' : 'hidden' " id='toggleMe'>
      <div id="class-metadata">
        
        
<div id="parent-class-section" class="nav-section">
  <h3>Parent</h3>

  <p class="link"><a href="Object.html">Object</a>
</div>

        
<div id="includes-section" class="nav-section">
  <h3>Included Modules</h3>

  <ul class="link-list">
    <li><a class="include" href="File/File/Constants.html">File::File::Constants</a>
    <li><a class="include" href="Enumerable.html">Enumerable</a>
  </ul>
</div>

        
        
<!-- Method Quickref -->
<div id="method-list-section" class="nav-section">
  <h3>Methods</h3>

  <ul class="link-list" role="directory">
    <li ><a href="#method-c-binread">::binread</a>
    <li ><a href="#method-c-binwrite">::binwrite</a>
    <li ><a href="#method-c-copy_stream">::copy_stream</a>
    <li ><a href="#method-c-for_fd">::for_fd</a>
    <li ><a href="#method-c-foreach">::foreach</a>
    <li ><a href="#method-c-new">::new</a>
    <li ><a href="#method-c-open">::open</a>
    <li ><a href="#method-c-pipe">::pipe</a>
    <li ><a href="#method-c-popen">::popen</a>
    <li ><a href="#method-c-read">::read</a>
    <li ><a href="#method-c-readlines">::readlines</a>
    <li ><a href="#method-c-select">::select</a>
    <li ><a href="#method-c-sysopen">::sysopen</a>
    <li ><a href="#method-c-try_convert">::try_convert</a>
    <li ><a href="#method-c-write">::write</a>
    <li ><a href="#method-i-3C-3C">#&lt;&lt;</a>
    <li ><a href="#method-i-advise">#advise</a>
    <li ><a href="#method-i-autoclose-3D">#autoclose=</a>
    <li ><a href="#method-i-autoclose-3F">#autoclose?</a>
    <li ><a href="#method-i-binmode">#binmode</a>
    <li ><a href="#method-i-binmode-3F">#binmode?</a>
    <li ><a href="#method-i-close">#close</a>
    <li ><a href="#method-i-close_on_exec-3D">#close_on_exec=</a>
    <li ><a href="#method-i-close_on_exec-3F">#close_on_exec?</a>
    <li ><a href="#method-i-close_read">#close_read</a>
    <li ><a href="#method-i-close_write">#close_write</a>
    <li ><a href="#method-i-closed-3F">#closed?</a>
    <li ><a href="#method-i-each">#each</a>
    <li ><a href="#method-i-each_byte">#each_byte</a>
    <li ><a href="#method-i-each_char">#each_char</a>
    <li ><a href="#method-i-each_codepoint">#each_codepoint</a>
    <li ><a href="#method-i-each_line">#each_line</a>
    <li ><a href="#method-i-eof">#eof</a>
    <li ><a href="#method-i-eof-3F">#eof?</a>
    <li ><a href="#method-i-external_encoding">#external_encoding</a>
    <li ><a href="#method-i-fcntl">#fcntl</a>
    <li ><a href="#method-i-fdatasync">#fdatasync</a>
    <li ><a href="#method-i-fileno">#fileno</a>
    <li ><a href="#method-i-flush">#flush</a>
    <li ><a href="#method-i-fsync">#fsync</a>
    <li ><a href="#method-i-getbyte">#getbyte</a>
    <li ><a href="#method-i-getc">#getc</a>
    <li ><a href="#method-i-gets">#gets</a>
    <li ><a href="#method-i-inspect">#inspect</a>
    <li ><a href="#method-i-internal_encoding">#internal_encoding</a>
    <li ><a href="#method-i-ioctl">#ioctl</a>
    <li ><a href="#method-i-isatty">#isatty</a>
    <li ><a href="#method-i-lineno">#lineno</a>
    <li ><a href="#method-i-lineno-3D">#lineno=</a>
    <li ><a href="#method-i-path">#path</a>
    <li ><a href="#method-i-pid">#pid</a>
    <li ><a href="#method-i-pos">#pos</a>
    <li ><a href="#method-i-pos-3D">#pos=</a>
    <li ><a href="#method-i-pread">#pread</a>
    <li ><a href="#method-i-print">#print</a>
    <li ><a href="#method-i-printf">#printf</a>
    <li ><a href="#method-i-putc">#putc</a>
    <li ><a href="#method-i-puts">#puts</a>
    <li ><a href="#method-i-pwrite">#pwrite</a>
    <li ><a href="#method-i-read">#read</a>
    <li ><a href="#method-i-read_nonblock">#read_nonblock</a>
    <li ><a href="#method-i-readbyte">#readbyte</a>
    <li ><a href="#method-i-readchar">#readchar</a>
    <li ><a href="#method-i-readline">#readline</a>
    <li ><a href="#method-i-readlines">#readlines</a>
    <li ><a href="#method-i-readpartial">#readpartial</a>
    <li ><a href="#method-i-reopen">#reopen</a>
    <li ><a href="#method-i-rewind">#rewind</a>
    <li ><a href="#method-i-seek">#seek</a>
    <li ><a href="#method-i-set_encoding">#set_encoding</a>
    <li ><a href="#method-i-set_encoding_by_bom">#set_encoding_by_bom</a>
    <li ><a href="#method-i-stat">#stat</a>
    <li ><a href="#method-i-sync">#sync</a>
    <li ><a href="#method-i-sync-3D">#sync=</a>
    <li ><a href="#method-i-sysread">#sysread</a>
    <li ><a href="#method-i-sysseek">#sysseek</a>
    <li ><a href="#method-i-syswrite">#syswrite</a>
    <li ><a href="#method-i-tell">#tell</a>
    <li ><a href="#method-i-timeout">#timeout</a>
    <li ><a href="#method-i-timeout-3D">#timeout=</a>
    <li ><a href="#method-i-to_i">#to_i</a>
    <li ><a href="#method-i-to_io">#to_io</a>
    <li ><a href="#method-i-to_path">#to_path</a>
    <li ><a href="#method-i-tty-3F">#tty?</a>
    <li ><a href="#method-i-ungetbyte">#ungetbyte</a>
    <li ><a href="#method-i-ungetc">#ungetc</a>
    <li ><a href="#method-i-wait">#wait</a>
    <li ><a href="#method-i-wait_priority">#wait_priority</a>
    <li ><a href="#method-i-wait_readable">#wait_readable</a>
    <li ><a href="#method-i-wait_writable">#wait_writable</a>
    <li ><a href="#method-i-write">#write</a>
    <li ><a href="#method-i-write_nonblock">#write_nonblock</a>
  </ul>
</div>

      </div>
     </div>
    </nav>


    <div id='extraz'><div class='adzbox-index'  >
      
     </div>         
    </div>

    <main role="main" aria-labelledby="class-IO">
    <h1 id="class-IO" class="class">
      class IO
    </h1>

    <section class="description">
    
<p>An instance of class IO (commonly called a <em>stream</em>) represents an input/output stream in the underlying operating system. Class IO is the basis for input and output in Ruby.</p>

<p>Class <a href="File.html"><code>File</code></a> is the only class in the Ruby core that is a subclass of IO. Some classes in the Ruby standard library are also subclasses of IO; these include TCPSocket and UDPSocket.</p>

<p>The global constant <a href="ARGF.html"><code>ARGF</code></a> (also accessible as <code>$&lt;</code>) provides an IO-like stream that allows access to all file paths found in ARGV (or found in STDIN if ARGV is empty). <a href="ARGF.html"><code>ARGF</code></a> is not itself a subclass of IO.</p>

<p>Class StringIO provides an IO-like stream that handles a <a href="String.html"><code>String</code></a>. StringIO is not itself a subclass of IO.</p>

<p>Important objects based on IO include:</p>
<ul><li>
<p>$stdin.</p>
</li><li>
<p>$stdout.</p>
</li><li>
<p>$stderr.</p>
</li><li>
<p>Instances of class <a href="File.html"><code>File</code></a>.</p>
</li></ul>

<p>An instance of IO may be created using:</p>
<ul><li>
<p><a href="IO.html#method-c-new"><code>IO.new</code></a>: returns a new IO object for the given integer file descriptor.</p>
</li><li>
<p><a href="IO.html#method-c-open"><code>IO.open</code></a>: passes a new IO object to the given block.</p>
</li><li>
<p><a href="IO.html#method-c-popen"><code>IO.popen</code></a>: returns a new IO object that is connected to the $stdin and $stdout of a newly-launched subprocess.</p>
</li><li>
<p><a href="Kernel.html#method-i-open"><code>Kernel#open</code></a>: Returns a new IO object connected to a given source: stream, file, or subprocess.</p>
</li></ul>

<p>Like a <a href="File.html"><code>File</code></a> stream, an IO stream has:</p>
<ul><li>
<p>A read/write mode, which may be read-only, write-only, or read/write; see <a href="File.html#class-File-label-Read-2FWrite+Mode">Read/Write Mode</a>.</p>
</li><li>
<p>A data mode, which may be text-only or binary; see <a href="File.html#class-File-label-Data+Mode">Data Mode</a>.</p>
</li><li>
<p>Internal and external encodings; see <a href="File.html#class-File-label-Encodings">Encodings</a>.</p>
</li></ul>

<p>And like other IO streams, it has:</p>
<ul><li>
<p>A position, which determines where in the stream the next read or write is to occur; see <a href="IO.html#class-IO-label-Position">Position</a>.</p>
</li><li>
<p>A line number, which is a special, line-oriented, “position” (different from the position mentioned above); see <a href="IO.html#class-IO-label-Line+Number">Line Number</a>.</p>
</li></ul>

<h2 id="class-IO-label-Extension+io-2Fconsole">Extension <code>io/console</code><span><a href="#class-IO-label-Extension+io-2Fconsole">&para;</a> <a href="#top">&uarr;</a></span></h2>

<p>Extension <code>io/console</code> provides numerous methods for interacting with the console; requiring it adds numerous methods to class IO.</p>

<h2 id="class-IO-label-Example+Files">Example Files<span><a href="#class-IO-label-Example+Files">&para;</a> <a href="#top">&uarr;</a></span></h2>

<p>Many examples here use these variables:</p>

<pre class="ruby"><span class="ruby-comment"># English text with newlines.</span>
<span class="ruby-identifier">text</span> = <span class="ruby-identifier">&lt;&lt;~EOT</span>
<span class="ruby-value">  First line
  Second line

  Fourth line
  Fifth line
</span><span class="ruby-identifier">EOT</span>

<span class="ruby-comment"># Russian text.</span>
<span class="ruby-identifier">russian</span> = <span class="ruby-string">&quot;\u{442 435 441 442}&quot;</span> <span class="ruby-comment"># =&gt; &quot;тест&quot;</span>

<span class="ruby-comment"># Binary data.</span>
<span class="ruby-identifier">data</span> = <span class="ruby-string">&quot;\u9990\u9991\u9992\u9993\u9994&quot;</span>

<span class="ruby-comment"># Text file.</span>
<span class="ruby-constant">File</span>.<span class="ruby-identifier">write</span>(<span class="ruby-string">&#39;t.txt&#39;</span>, <span class="ruby-identifier">text</span>)

<span class="ruby-comment"># File with Russian text.</span>
<span class="ruby-constant">File</span>.<span class="ruby-identifier">write</span>(<span class="ruby-string">&#39;t.rus&#39;</span>, <span class="ruby-identifier">russian</span>)

<span class="ruby-comment"># File with binary data.</span>
<span class="ruby-identifier">f</span> = <span class="ruby-constant">File</span>.<span class="ruby-identifier">new</span>(<span class="ruby-string">&#39;t.dat&#39;</span>, <span class="ruby-string">&#39;wb:UTF-16&#39;</span>)
<span class="ruby-identifier">f</span>.<span class="ruby-identifier">write</span>(<span class="ruby-identifier">data</span>)
<span class="ruby-identifier">f</span>.<span class="ruby-identifier">close</span>
</pre>

<h2 id="class-IO-label-Open+Options">Open Options<span><a href="#class-IO-label-Open+Options">&para;</a> <a href="#top">&uarr;</a></span></h2>

<p>A number of IO methods accept optional keyword arguments that determine how a new stream is to be opened:</p>
<ul><li>
<p><code>:mode</code>: Stream mode.</p>
</li><li>
<p><code>:flags</code>: <a href="Integer.html"><code>Integer</code></a> file open flags; If <code>mode</code> is also given, the two are bitwise-ORed.</p>
</li><li>
<p><code>:external_encoding</code>: External encoding for the stream.</p>
</li><li>
<p><code>:internal_encoding</code>: Internal encoding for the stream. <code>&#39;-&#39;</code> is a synonym for the default internal encoding. If the value is <code>nil</code> no conversion occurs.</p>
</li><li>
<p><code>:encoding</code>: Specifies external and internal encodings as <code>&#39;extern:intern&#39;</code>.</p>
</li><li>
<p><code>:textmode</code>: If a truthy value, specifies the mode as text-only, binary otherwise.</p>
</li><li>
<p><code>:binmode</code>: If a truthy value, specifies the mode as binary, text-only otherwise.</p>
</li><li>
<p><code>:autoclose</code>: If a truthy value, specifies that the <code>fd</code> will close when the stream closes; otherwise it remains open.</p>
</li><li>
<p><code>:path:</code> If a string value is provided, it is used in <a href="IO.html#method-i-inspect"><code>inspect</code></a> and is available as <a href="IO.html#method-i-path"><code>path</code></a> method.</p>
</li></ul>

<p>Also available are the options offered in <a href="String.html#method-i-encode"><code>String#encode</code></a>, which may control conversion between external and internal encoding.</p>

<h2 id="class-IO-label-Basic+IO">Basic IO<span><a href="#class-IO-label-Basic+IO">&para;</a> <a href="#top">&uarr;</a></span></h2>

<p>You can perform basic stream IO with these methods, which typically operate on multi-byte strings:</p>
<ul><li>
<p><a href="IO.html#method-i-read"><code>IO#read</code></a>: Reads and returns some or all of the remaining bytes from the stream.</p>
</li><li>
<p><a href="IO.html#method-i-write"><code>IO#write</code></a>: Writes zero or more strings to the stream; each given object that is not already a string is converted via <code>to_s</code>.</p>
</li></ul>

<h3 id="class-IO-label-Position">Position<span><a href="#class-IO-label-Position">&para;</a> <a href="#top">&uarr;</a></span></h3>

<p>An IO stream has a nonnegative integer <em>position</em>, which is the byte offset at which the next read or write is to occur. A new stream has position zero (and line number zero); method <code>rewind</code> resets the position (and line number) to zero.</p>

<p>The relevant methods:</p>
<ul><li>
<p><a href="IO.html#method-i-tell"><code>IO#tell</code></a> (aliased as <code>#pos</code>): Returns the current position (in bytes) in the stream.</p>
</li><li>
<p><a href="IO.html#method-i-pos-3D"><code>IO#pos=</code></a>: Sets the position of the stream to a given integer <code>new_position</code> (in bytes).</p>
</li><li>
<p><a href="IO.html#method-i-seek"><code>IO#seek</code></a>: Sets the position of the stream to a given integer <code>offset</code> (in bytes), relative to a given position <code>whence</code> (indicating the beginning, end, or current position).</p>
</li><li>
<p><a href="IO.html#method-i-rewind"><code>IO#rewind</code></a>: Positions the stream at the beginning (also resetting the line number).</p>
</li></ul>

<h3 id="class-IO-label-Open+and+Closed+Streams">Open and Closed Streams<span><a href="#class-IO-label-Open+and+Closed+Streams">&para;</a> <a href="#top">&uarr;</a></span></h3>

<p>A new IO stream may be open for reading, open for writing, or both.</p>

<p>A stream is automatically closed when claimed by the garbage collector.</p>

<p>Attempted reading or writing on a closed stream raises an exception.</p>

<p>The relevant methods:</p>
<ul><li>
<p><a href="IO.html#method-i-close"><code>IO#close</code></a>: Closes the stream for both reading and writing.</p>
</li><li>
<p><a href="IO.html#method-i-close_read"><code>IO#close_read</code></a>: Closes the stream for reading.</p>
</li><li>
<p><a href="IO.html#method-i-close_write"><code>IO#close_write</code></a>: Closes the stream for writing.</p>
</li><li>
<p><a href="IO.html#method-i-closed-3F"><code>IO#closed?</code></a>: Returns whether the stream is closed.</p>
</li></ul>

<h3 id="class-IO-label-End-of-Stream">End-of-Stream<span><a href="#class-IO-label-End-of-Stream">&para;</a> <a href="#top">&uarr;</a></span></h3>

<p>You can query whether a stream is positioned at its end:</p>
<ul><li>
<p><a href="IO.html#method-i-eof-3F"><code>IO#eof?</code></a> (also aliased as <code>#eof</code>): Returns whether the stream is at end-of-stream.</p>
</li></ul>

<p>You can reposition to end-of-stream by using method <a href="IO.html#method-i-seek"><code>IO#seek</code></a>:</p>

<pre class="ruby"><span class="ruby-identifier">f</span> = <span class="ruby-constant">File</span>.<span class="ruby-identifier">new</span>(<span class="ruby-string">&#39;t.txt&#39;</span>)
<span class="ruby-identifier">f</span>.<span class="ruby-identifier">eof?</span> <span class="ruby-comment"># =&gt; false</span>
<span class="ruby-identifier">f</span>.<span class="ruby-identifier">seek</span>(<span class="ruby-value">0</span>, <span class="ruby-value">:END</span>)
<span class="ruby-identifier">f</span>.<span class="ruby-identifier">eof?</span> <span class="ruby-comment"># =&gt; true</span>
<span class="ruby-identifier">f</span>.<span class="ruby-identifier">close</span>
</pre>

<p>Or by reading all stream content (which is slower than using <a href="IO.html#method-i-seek"><code>IO#seek</code></a>):</p>

<pre class="ruby"><span class="ruby-identifier">f</span>.<span class="ruby-identifier">rewind</span>
<span class="ruby-identifier">f</span>.<span class="ruby-identifier">eof?</span> <span class="ruby-comment"># =&gt; false</span>
<span class="ruby-identifier">f</span>.<span class="ruby-identifier">read</span> <span class="ruby-comment"># =&gt; &quot;First line\nSecond line\n\nFourth line\nFifth line\n&quot;</span>
<span class="ruby-identifier">f</span>.<span class="ruby-identifier">eof?</span> <span class="ruby-comment"># =&gt; true</span>
</pre>

<h2 id="class-IO-label-Line+IO">Line IO<span><a href="#class-IO-label-Line+IO">&para;</a> <a href="#top">&uarr;</a></span></h2>

<p>You can read an IO stream line-by-line using these methods:</p>
<ul><li>
<p><a href="IO.html#method-i-each_line"><code>IO#each_line</code></a>: Reads each remaining line, passing it to the given block.</p>
</li><li>
<p><a href="IO.html#method-i-gets"><code>IO#gets</code></a>: Returns the next line.</p>
</li><li>
<p><a href="IO.html#method-i-readline"><code>IO#readline</code></a>: Like <a href="IO.html#method-i-gets"><code>gets</code></a>, but raises an exception at end-of-stream.</p>
</li><li>
<p><a href="IO.html#method-i-readlines"><code>IO#readlines</code></a>: Returns all remaining lines in an array.</p>
</li></ul>

<p>Each of these reader methods accepts:</p>
<ul><li>
<p>An optional line separator, <code>sep</code>; see <a href="IO.html#class-IO-label-Line+Separator">Line Separator</a>.</p>
</li><li>
<p>An optional line-size limit, <code>limit</code>; see <a href="IO.html#class-IO-label-Line+Limit">Line Limit</a>.</p>
</li></ul>

<p>For each of these reader methods, reading may begin mid-line, depending on the stream’s position; see <a href="IO.html#class-IO-label-Position">Position</a>:</p>

<pre class="ruby"><span class="ruby-identifier">f</span> = <span class="ruby-constant">File</span>.<span class="ruby-identifier">new</span>(<span class="ruby-string">&#39;t.txt&#39;</span>)
<span class="ruby-identifier">f</span>.<span class="ruby-identifier">pos</span> = <span class="ruby-value">27</span>
<span class="ruby-identifier">f</span>.<span class="ruby-identifier">each_line</span> {<span class="ruby-operator">|</span><span class="ruby-identifier">line</span><span class="ruby-operator">|</span> <span class="ruby-identifier">p</span> <span class="ruby-identifier">line</span> }
<span class="ruby-identifier">f</span>.<span class="ruby-identifier">close</span>
</pre>

<p>Output:</p>

<pre class="ruby"><span class="ruby-string">&quot;rth line\n&quot;</span>
<span class="ruby-string">&quot;Fifth line\n&quot;</span>
</pre>

<p>You can write to an IO stream line-by-line using this method:</p>
<ul><li>
<p><a href="IO.html#method-i-puts"><code>IO#puts</code></a>: Writes objects to the stream.</p>
</li></ul>

<h3 id="class-IO-label-Line+Separator">Line Separator<span><a href="#class-IO-label-Line+Separator">&para;</a> <a href="#top">&uarr;</a></span></h3>

<p>Each of these methods uses a <em>line separator</em>, which is the string that delimits lines:</p>
<ul><li>
<p><a href="IO.html#method-c-foreach"><code>IO.foreach</code></a>.</p>
</li><li>
<p><a href="IO.html#method-c-readlines"><code>IO.readlines</code></a>.</p>
</li><li>
<p><a href="IO.html#method-i-each_line"><code>IO#each_line</code></a>.</p>
</li><li>
<p><a href="IO.html#method-i-gets"><code>IO#gets</code></a>.</p>
</li><li>
<p><a href="IO.html#method-i-readline"><code>IO#readline</code></a>.</p>
</li><li>
<p><a href="IO.html#method-i-readlines"><code>IO#readlines</code></a>.</p>
</li></ul>

<p>The default line separator is the given by the global variable <code>$/</code>, whose value is by default <code>&quot;\n&quot;</code>. The line to be read next is all data from the current position to the next line separator:</p>

<pre class="ruby"><span class="ruby-identifier">f</span> = <span class="ruby-constant">File</span>.<span class="ruby-identifier">new</span>(<span class="ruby-string">&#39;t.txt&#39;</span>)
<span class="ruby-identifier">f</span>.<span class="ruby-identifier">gets</span> <span class="ruby-comment"># =&gt; &quot;First line\n&quot;</span>
<span class="ruby-identifier">f</span>.<span class="ruby-identifier">gets</span> <span class="ruby-comment"># =&gt; &quot;Second line\n&quot;</span>
<span class="ruby-identifier">f</span>.<span class="ruby-identifier">gets</span> <span class="ruby-comment"># =&gt; &quot;\n&quot;</span>
<span class="ruby-identifier">f</span>.<span class="ruby-identifier">gets</span> <span class="ruby-comment"># =&gt; &quot;Fourth line\n&quot;</span>
<span class="ruby-identifier">f</span>.<span class="ruby-identifier">gets</span> <span class="ruby-comment"># =&gt; &quot;Fifth line\n&quot;</span>
<span class="ruby-identifier">f</span>.<span class="ruby-identifier">close</span>
</pre>

<p>You can specify a different line separator:</p>

<pre class="ruby"><span class="ruby-identifier">f</span> = <span class="ruby-constant">File</span>.<span class="ruby-identifier">new</span>(<span class="ruby-string">&#39;t.txt&#39;</span>)
<span class="ruby-identifier">f</span>.<span class="ruby-identifier">gets</span>(<span class="ruby-string">&#39;l&#39;</span>)   <span class="ruby-comment"># =&gt; &quot;First l&quot;</span>
<span class="ruby-identifier">f</span>.<span class="ruby-identifier">gets</span>(<span class="ruby-string">&#39;li&#39;</span>)  <span class="ruby-comment"># =&gt; &quot;ine\nSecond li&quot;</span>
<span class="ruby-identifier">f</span>.<span class="ruby-identifier">gets</span>(<span class="ruby-string">&#39;lin&#39;</span>) <span class="ruby-comment"># =&gt; &quot;ne\n\nFourth lin&quot;</span>
<span class="ruby-identifier">f</span>.<span class="ruby-identifier">gets</span>        <span class="ruby-comment"># =&gt; &quot;e\n&quot;</span>
<span class="ruby-identifier">f</span>.<span class="ruby-identifier">close</span>
</pre>

<p>There are two special line separators:</p>
<ul><li>
<p><code>nil</code>: The entire stream is read into a single string:</p>

<pre class="ruby"><span class="ruby-identifier">f</span> = <span class="ruby-constant">File</span>.<span class="ruby-identifier">new</span>(<span class="ruby-string">&#39;t.txt&#39;</span>)
<span class="ruby-identifier">f</span>.<span class="ruby-identifier">gets</span>(<span class="ruby-keyword">nil</span>) <span class="ruby-comment"># =&gt; &quot;First line\nSecond line\n\nFourth line\nFifth line\n&quot;</span>
<span class="ruby-identifier">f</span>.<span class="ruby-identifier">close</span>
</pre>
</li><li>
<p><code>&#39;&#39;</code> (the empty string): The next “paragraph” is read (paragraphs being separated by two consecutive line separators):</p>

<pre class="ruby"><span class="ruby-identifier">f</span> = <span class="ruby-constant">File</span>.<span class="ruby-identifier">new</span>(<span class="ruby-string">&#39;t.txt&#39;</span>)
<span class="ruby-identifier">f</span>.<span class="ruby-identifier">gets</span>(<span class="ruby-string">&#39;&#39;</span>) <span class="ruby-comment"># =&gt; &quot;First line\nSecond line\n\n&quot;</span>
<span class="ruby-identifier">f</span>.<span class="ruby-identifier">gets</span>(<span class="ruby-string">&#39;&#39;</span>) <span class="ruby-comment"># =&gt; &quot;Fourth line\nFifth line\n&quot;</span>
<span class="ruby-identifier">f</span>.<span class="ruby-identifier">close</span>
</pre>
</li></ul>

<h3 id="class-IO-label-Line+Limit">Line Limit<span><a href="#class-IO-label-Line+Limit">&para;</a> <a href="#top">&uarr;</a></span></h3>

<p>Each of these methods uses a <em>line limit</em>, which specifies that the number of bytes returned may not be (much) longer than the given <code>limit</code>;</p>
<ul><li>
<p><a href="IO.html#method-c-foreach"><code>IO.foreach</code></a>.</p>
</li><li>
<p><a href="IO.html#method-c-readlines"><code>IO.readlines</code></a>.</p>
</li><li>
<p><a href="IO.html#method-i-each_line"><code>IO#each_line</code></a>.</p>
</li><li>
<p><a href="IO.html#method-i-gets"><code>IO#gets</code></a>.</p>
</li><li>
<p><a href="IO.html#method-i-readline"><code>IO#readline</code></a>.</p>
</li><li>
<p><a href="IO.html#method-i-readlines"><code>IO#readlines</code></a>.</p>
</li></ul>

<p>A multi-byte character will not be split, and so a line may be slightly longer than the given limit.</p>

<p>If <code>limit</code> is not given, the line is determined only by <code>sep</code>.</p>

<pre class="ruby"><span class="ruby-comment"># Text with 1-byte characters.</span>
<span class="ruby-constant">File</span>.<span class="ruby-identifier">open</span>(<span class="ruby-string">&#39;t.txt&#39;</span>) {<span class="ruby-operator">|</span><span class="ruby-identifier">f</span><span class="ruby-operator">|</span> <span class="ruby-identifier">f</span>.<span class="ruby-identifier">gets</span>(<span class="ruby-value">1</span>) }  <span class="ruby-comment"># =&gt; &quot;F&quot;</span>
<span class="ruby-constant">File</span>.<span class="ruby-identifier">open</span>(<span class="ruby-string">&#39;t.txt&#39;</span>) {<span class="ruby-operator">|</span><span class="ruby-identifier">f</span><span class="ruby-operator">|</span> <span class="ruby-identifier">f</span>.<span class="ruby-identifier">gets</span>(<span class="ruby-value">2</span>) }  <span class="ruby-comment"># =&gt; &quot;Fi&quot;</span>
<span class="ruby-constant">File</span>.<span class="ruby-identifier">open</span>(<span class="ruby-string">&#39;t.txt&#39;</span>) {<span class="ruby-operator">|</span><span class="ruby-identifier">f</span><span class="ruby-operator">|</span> <span class="ruby-identifier">f</span>.<span class="ruby-identifier">gets</span>(<span class="ruby-value">3</span>) }  <span class="ruby-comment"># =&gt; &quot;Fir&quot;</span>
<span class="ruby-constant">File</span>.<span class="ruby-identifier">open</span>(<span class="ruby-string">&#39;t.txt&#39;</span>) {<span class="ruby-operator">|</span><span class="ruby-identifier">f</span><span class="ruby-operator">|</span> <span class="ruby-identifier">f</span>.<span class="ruby-identifier">gets</span>(<span class="ruby-value">4</span>) }  <span class="ruby-comment"># =&gt; &quot;Firs&quot;</span>
<span class="ruby-comment"># No more than one line.</span>
<span class="ruby-constant">File</span>.<span class="ruby-identifier">open</span>(<span class="ruby-string">&#39;t.txt&#39;</span>) {<span class="ruby-operator">|</span><span class="ruby-identifier">f</span><span class="ruby-operator">|</span> <span class="ruby-identifier">f</span>.<span class="ruby-identifier">gets</span>(<span class="ruby-value">10</span>) } <span class="ruby-comment"># =&gt; &quot;First line&quot;</span>
<span class="ruby-constant">File</span>.<span class="ruby-identifier">open</span>(<span class="ruby-string">&#39;t.txt&#39;</span>) {<span class="ruby-operator">|</span><span class="ruby-identifier">f</span><span class="ruby-operator">|</span> <span class="ruby-identifier">f</span>.<span class="ruby-identifier">gets</span>(<span class="ruby-value">11</span>) } <span class="ruby-comment"># =&gt; &quot;First line\n&quot;</span>
<span class="ruby-constant">File</span>.<span class="ruby-identifier">open</span>(<span class="ruby-string">&#39;t.txt&#39;</span>) {<span class="ruby-operator">|</span><span class="ruby-identifier">f</span><span class="ruby-operator">|</span> <span class="ruby-identifier">f</span>.<span class="ruby-identifier">gets</span>(<span class="ruby-value">12</span>) } <span class="ruby-comment"># =&gt; &quot;First line\n&quot;</span>

<span class="ruby-comment"># Text with 2-byte characters, which will not be split.</span>
<span class="ruby-constant">File</span>.<span class="ruby-identifier">open</span>(<span class="ruby-string">&#39;t.rus&#39;</span>) {<span class="ruby-operator">|</span><span class="ruby-identifier">f</span><span class="ruby-operator">|</span> <span class="ruby-identifier">f</span>.<span class="ruby-identifier">gets</span>(<span class="ruby-value">1</span>).<span class="ruby-identifier">size</span> } <span class="ruby-comment"># =&gt; 1</span>
<span class="ruby-constant">File</span>.<span class="ruby-identifier">open</span>(<span class="ruby-string">&#39;t.rus&#39;</span>) {<span class="ruby-operator">|</span><span class="ruby-identifier">f</span><span class="ruby-operator">|</span> <span class="ruby-identifier">f</span>.<span class="ruby-identifier">gets</span>(<span class="ruby-value">2</span>).<span class="ruby-identifier">size</span> } <span class="ruby-comment"># =&gt; 1</span>
<span class="ruby-constant">File</span>.<span class="ruby-identifier">open</span>(<span class="ruby-string">&#39;t.rus&#39;</span>) {<span class="ruby-operator">|</span><span class="ruby-identifier">f</span><span class="ruby-operator">|</span> <span class="ruby-identifier">f</span>.<span class="ruby-identifier">gets</span>(<span class="ruby-value">3</span>).<span class="ruby-identifier">size</span> } <span class="ruby-comment"># =&gt; 2</span>
<span class="ruby-constant">File</span>.<span class="ruby-identifier">open</span>(<span class="ruby-string">&#39;t.rus&#39;</span>) {<span class="ruby-operator">|</span><span class="ruby-identifier">f</span><span class="ruby-operator">|</span> <span class="ruby-identifier">f</span>.<span class="ruby-identifier">gets</span>(<span class="ruby-value">4</span>).<span class="ruby-identifier">size</span> } <span class="ruby-comment"># =&gt; 2</span>
</pre>

<h3 id="class-IO-label-Line+Separator+and+Line+Limit">Line Separator and Line Limit<span><a href="#class-IO-label-Line+Separator+and+Line+Limit">&para;</a> <a href="#top">&uarr;</a></span></h3>

<p>With arguments <code>sep</code> and <code>limit</code> given, combines the two behaviors:</p>
<ul><li>
<p>Returns the next line as determined by line separator <code>sep</code>.</p>
</li><li>
<p>But returns no more bytes than are allowed by the limit.</p>
</li></ul>

<p>Example:</p>

<pre class="ruby"><span class="ruby-constant">File</span>.<span class="ruby-identifier">open</span>(<span class="ruby-string">&#39;t.txt&#39;</span>) {<span class="ruby-operator">|</span><span class="ruby-identifier">f</span><span class="ruby-operator">|</span> <span class="ruby-identifier">f</span>.<span class="ruby-identifier">gets</span>(<span class="ruby-string">&#39;li&#39;</span>, <span class="ruby-value">20</span>) } <span class="ruby-comment"># =&gt; &quot;First li&quot;</span>
<span class="ruby-constant">File</span>.<span class="ruby-identifier">open</span>(<span class="ruby-string">&#39;t.txt&#39;</span>) {<span class="ruby-operator">|</span><span class="ruby-identifier">f</span><span class="ruby-operator">|</span> <span class="ruby-identifier">f</span>.<span class="ruby-identifier">gets</span>(<span class="ruby-string">&#39;li&#39;</span>, <span class="ruby-value">2</span>) }  <span class="ruby-comment"># =&gt; &quot;Fi&quot;</span>
</pre>

<h3 id="class-IO-label-Line+Number">Line Number<span><a href="#class-IO-label-Line+Number">&para;</a> <a href="#top">&uarr;</a></span></h3>

<p>A readable IO stream has a non-negative integer <em>line number</em>.</p>

<p>The relevant methods:</p>
<ul><li>
<p><a href="IO.html#method-i-lineno"><code>IO#lineno</code></a>: Returns the line number.</p>
</li><li>
<p><a href="IO.html#method-i-lineno-3D"><code>IO#lineno=</code></a>: Resets and returns the line number.</p>
</li></ul>

<p>Unless modified by a call to method <a href="IO.html#method-i-lineno-3D"><code>IO#lineno=</code></a>, the line number is the number of lines read by certain line-oriented methods, according to the given line separator <code>sep</code>:</p>
<ul><li>
<p><a href="IO.html#method-c-foreach"><code>IO.foreach</code></a>: Increments the line number on each call to the block.</p>
</li><li>
<p><a href="IO.html#method-i-each_line"><code>IO#each_line</code></a>: Increments the line number on each call to the block.</p>
</li><li>
<p><a href="IO.html#method-i-gets"><code>IO#gets</code></a>: Increments the line number.</p>
</li><li>
<p><a href="IO.html#method-i-readline"><code>IO#readline</code></a>: Increments the line number.</p>
</li><li>
<p><a href="IO.html#method-i-readlines"><code>IO#readlines</code></a>: Increments the line number for each line read.</p>
</li></ul>

<p>A new stream is initially has line number zero (and position zero); method <code>rewind</code> resets the line number (and position) to zero:</p>

<pre class="ruby"><span class="ruby-identifier">f</span> = <span class="ruby-constant">File</span>.<span class="ruby-identifier">new</span>(<span class="ruby-string">&#39;t.txt&#39;</span>)
<span class="ruby-identifier">f</span>.<span class="ruby-identifier">lineno</span> <span class="ruby-comment"># =&gt; 0</span>
<span class="ruby-identifier">f</span>.<span class="ruby-identifier">gets</span>   <span class="ruby-comment"># =&gt; &quot;First line\n&quot;</span>
<span class="ruby-identifier">f</span>.<span class="ruby-identifier">lineno</span> <span class="ruby-comment"># =&gt; 1</span>
<span class="ruby-identifier">f</span>.<span class="ruby-identifier">rewind</span>
<span class="ruby-identifier">f</span>.<span class="ruby-identifier">lineno</span> <span class="ruby-comment"># =&gt; 0</span>
<span class="ruby-identifier">f</span>.<span class="ruby-identifier">close</span>
</pre>

<p>Reading lines from a stream usually changes its line number:</p>

<pre class="ruby"><span class="ruby-identifier">f</span> = <span class="ruby-constant">File</span>.<span class="ruby-identifier">new</span>(<span class="ruby-string">&#39;t.txt&#39;</span>, <span class="ruby-string">&#39;r&#39;</span>)
<span class="ruby-identifier">f</span>.<span class="ruby-identifier">lineno</span>   <span class="ruby-comment"># =&gt; 0</span>
<span class="ruby-identifier">f</span>.<span class="ruby-identifier">readline</span> <span class="ruby-comment"># =&gt; &quot;This is line one.\n&quot;</span>
<span class="ruby-identifier">f</span>.<span class="ruby-identifier">lineno</span>   <span class="ruby-comment"># =&gt; 1</span>
<span class="ruby-identifier">f</span>.<span class="ruby-identifier">readline</span> <span class="ruby-comment"># =&gt; &quot;This is the second line.\n&quot;</span>
<span class="ruby-identifier">f</span>.<span class="ruby-identifier">lineno</span>   <span class="ruby-comment"># =&gt; 2</span>
<span class="ruby-identifier">f</span>.<span class="ruby-identifier">readline</span> <span class="ruby-comment"># =&gt; &quot;Here&#39;s the third line.\n&quot;</span>
<span class="ruby-identifier">f</span>.<span class="ruby-identifier">lineno</span>   <span class="ruby-comment"># =&gt; 3</span>
<span class="ruby-identifier">f</span>.<span class="ruby-identifier">eof?</span>     <span class="ruby-comment"># =&gt; true</span>
<span class="ruby-identifier">f</span>.<span class="ruby-identifier">close</span>
</pre>

<p>Iterating over lines in a stream usually changes its line number:</p>

<pre class="ruby"><span class="ruby-constant">File</span>.<span class="ruby-identifier">open</span>(<span class="ruby-string">&#39;t.txt&#39;</span>) <span class="ruby-keyword">do</span> <span class="ruby-operator">|</span><span class="ruby-identifier">f</span><span class="ruby-operator">|</span>
  <span class="ruby-identifier">f</span>.<span class="ruby-identifier">each_line</span> <span class="ruby-keyword">do</span> <span class="ruby-operator">|</span><span class="ruby-identifier">line</span><span class="ruby-operator">|</span>
    <span class="ruby-identifier">p</span> <span class="ruby-node">&quot;position=#{f.pos} eof?=#{f.eof?} lineno=#{f.lineno}&quot;</span>
  <span class="ruby-keyword">end</span>
<span class="ruby-keyword">end</span>
</pre>

<p>Output:</p>

<pre class="ruby"><span class="ruby-string">&quot;position=11 eof?=false lineno=1&quot;</span>
<span class="ruby-string">&quot;position=23 eof?=false lineno=2&quot;</span>
<span class="ruby-string">&quot;position=24 eof?=false lineno=3&quot;</span>
<span class="ruby-string">&quot;position=36 eof?=false lineno=4&quot;</span>
<span class="ruby-string">&quot;position=47 eof?=true lineno=5&quot;</span>
</pre>

<p>Unlike the stream’s <a href="IO.html#class-IO-label-Position">position</a>, the line number does not affect where the next read or write will occur:</p>

<pre class="ruby"><span class="ruby-identifier">f</span> = <span class="ruby-constant">File</span>.<span class="ruby-identifier">new</span>(<span class="ruby-string">&#39;t.txt&#39;</span>)
<span class="ruby-identifier">f</span>.<span class="ruby-identifier">lineno</span> = <span class="ruby-value">1000</span>
<span class="ruby-identifier">f</span>.<span class="ruby-identifier">lineno</span> <span class="ruby-comment"># =&gt; 1000</span>
<span class="ruby-identifier">f</span>.<span class="ruby-identifier">gets</span>   <span class="ruby-comment"># =&gt; &quot;First line\n&quot;</span>
<span class="ruby-identifier">f</span>.<span class="ruby-identifier">lineno</span> <span class="ruby-comment"># =&gt; 1001</span>
<span class="ruby-identifier">f</span>.<span class="ruby-identifier">close</span>
</pre>

<p>Associated with the line number is the global variable <code>$.</code>:</p>
<ul><li>
<p>When a stream is opened, <code>$.</code> is not set; its value is left over from previous activity in the process:</p>

<pre class="ruby"><span class="ruby-identifier">$.</span> = <span class="ruby-value">41</span>
<span class="ruby-identifier">f</span> = <span class="ruby-constant">File</span>.<span class="ruby-identifier">new</span>(<span class="ruby-string">&#39;t.txt&#39;</span>)
<span class="ruby-identifier">$.</span> = <span class="ruby-value">41</span>
<span class="ruby-comment"># =&gt; 41</span>
<span class="ruby-identifier">f</span>.<span class="ruby-identifier">close</span>
</pre>
</li><li>
<p>When a stream is read, <code>#.</code> is set to the line number for that stream:</p>

<pre class="ruby"><span class="ruby-identifier">f0</span> = <span class="ruby-constant">File</span>.<span class="ruby-identifier">new</span>(<span class="ruby-string">&#39;t.txt&#39;</span>)
<span class="ruby-identifier">f1</span> = <span class="ruby-constant">File</span>.<span class="ruby-identifier">new</span>(<span class="ruby-string">&#39;t.dat&#39;</span>)
<span class="ruby-identifier">f0</span>.<span class="ruby-identifier">readlines</span> <span class="ruby-comment"># =&gt; [&quot;First line\n&quot;, &quot;Second line\n&quot;, &quot;\n&quot;, &quot;Fourth line\n&quot;, &quot;Fifth line\n&quot;]</span>
<span class="ruby-identifier">$.</span>           <span class="ruby-comment"># =&gt; 5</span>
<span class="ruby-identifier">f1</span>.<span class="ruby-identifier">readlines</span> <span class="ruby-comment"># =&gt; [&quot;\xFE\xFF\x99\x90\x99\x91\x99\x92\x99\x93\x99\x94&quot;]</span>
<span class="ruby-identifier">$.</span>           <span class="ruby-comment"># =&gt; 1</span>
<span class="ruby-identifier">f0</span>.<span class="ruby-identifier">close</span>
<span class="ruby-identifier">f1</span>.<span class="ruby-identifier">close</span>
</pre>
</li><li>
<p>Methods <a href="IO.html#method-i-rewind"><code>IO#rewind</code></a> and <a href="IO.html#method-i-seek"><code>IO#seek</code></a> do not affect <code>$.</code>:</p>

<pre class="ruby"><span class="ruby-identifier">f</span> = <span class="ruby-constant">File</span>.<span class="ruby-identifier">new</span>(<span class="ruby-string">&#39;t.txt&#39;</span>)
<span class="ruby-identifier">f</span>.<span class="ruby-identifier">readlines</span> <span class="ruby-comment"># =&gt; [&quot;First line\n&quot;, &quot;Second line\n&quot;, &quot;\n&quot;, &quot;Fourth line\n&quot;, &quot;Fifth line\n&quot;]</span>
<span class="ruby-identifier">$.</span>          <span class="ruby-comment"># =&gt; 5</span>
<span class="ruby-identifier">f</span>.<span class="ruby-identifier">rewind</span>
<span class="ruby-identifier">f</span>.<span class="ruby-identifier">seek</span>(<span class="ruby-value">0</span>, <span class="ruby-value">:SET</span>)
<span class="ruby-identifier">$.</span>          <span class="ruby-comment"># =&gt; 5</span>
<span class="ruby-identifier">f</span>.<span class="ruby-identifier">close</span>
</pre>
</li></ul>

<h2 id="class-IO-label-Character+IO">Character IO<span><a href="#class-IO-label-Character+IO">&para;</a> <a href="#top">&uarr;</a></span></h2>

<p>You can process an IO stream character-by-character using these methods:</p>
<ul><li>
<p><a href="IO.html#method-i-getc"><code>IO#getc</code></a>: Reads and returns the next character from the stream.</p>
</li><li>
<p><a href="IO.html#method-i-readchar"><code>IO#readchar</code></a>: Like <a href="IO.html#method-i-getc"><code>getc</code></a>, but raises an exception at end-of-stream.</p>
</li><li>
<p><a href="IO.html#method-i-ungetc"><code>IO#ungetc</code></a>: Pushes back (“unshifts”) a character or integer onto the stream.</p>
</li><li>
<p><a href="IO.html#method-i-putc"><code>IO#putc</code></a>: Writes a character to the stream.</p>
</li><li>
<p><a href="IO.html#method-i-each_char"><code>IO#each_char</code></a>: Reads each remaining character in the stream, passing the character to the given block.</p>
</li></ul>

<h2 id="class-IO-label-Byte+IO">Byte IO<span><a href="#class-IO-label-Byte+IO">&para;</a> <a href="#top">&uarr;</a></span></h2>

<p>You can process an IO stream byte-by-byte using these methods:</p>
<ul><li>
<p><a href="IO.html#method-i-getbyte"><code>IO#getbyte</code></a>: Returns the next 8-bit byte as an integer in range 0..255.</p>
</li><li>
<p><a href="IO.html#method-i-readbyte"><code>IO#readbyte</code></a>: Like <a href="IO.html#method-i-getbyte"><code>getbyte</code></a>, but raises an exception if at end-of-stream.</p>
</li><li>
<p><a href="IO.html#method-i-ungetbyte"><code>IO#ungetbyte</code></a>: Pushes back (“unshifts”) a byte back onto the stream.</p>
</li><li>
<p><a href="IO.html#method-i-each_byte"><code>IO#each_byte</code></a>: Reads each remaining byte in the stream, passing the byte to the given block.</p>
</li></ul>

<h2 id="class-IO-label-Codepoint+IO">Codepoint IO<span><a href="#class-IO-label-Codepoint+IO">&para;</a> <a href="#top">&uarr;</a></span></h2>

<p>You can process an IO stream codepoint-by-codepoint:</p>
<ul><li>
<p><a href="IO.html#method-i-each_codepoint"><code>IO#each_codepoint</code></a>: Reads each remaining codepoint, passing it to the given block.</p>
</li></ul>

<h2 id="class-IO-label-What-27s+Here">What’s Here<span><a href="#class-IO-label-What-27s+Here">&para;</a> <a href="#top">&uarr;</a></span></h2>

<p>First, what’s elsewhere. Class IO:</p>
<ul><li>
<p>Inherits from <a href="Object.html#class-Object-label-What-27s+Here">class Object</a>.</p>
</li><li>
<p>Includes <a href="Enumerable.html#module-Enumerable-label-What-27s+Here">module Enumerable</a>, which provides dozens of additional methods.</p>
</li></ul>

<p>Here, class IO provides methods that are useful for:</p>
<ul><li>
<p><a href="IO.html#class-IO-label-Creating">Creating</a></p>
</li><li>
<p><a href="IO.html#class-IO-label-Reading">Reading</a></p>
</li><li>
<p><a href="IO.html#class-IO-label-Writing">Writing</a></p>
</li><li>
<p><a href="IO.html#class-IO-label-Positioning">Positioning</a></p>
</li><li>
<p><a href="IO.html#class-IO-label-Iterating">Iterating</a></p>
</li><li>
<p><a href="IO.html#class-IO-label-Settings">Settings</a></p>
</li><li>
<p><a href="IO.html#class-IO-label-Querying">Querying</a></p>
</li><li>
<p><a href="IO.html#class-IO-label-Buffering">Buffering</a></p>
</li><li>
<p><a href="IO.html#class-IO-label-Low-Level+Access">Low-Level Access</a></p>
</li><li>
<p><a href="IO.html#class-IO-label-Other">Other</a></p>
</li></ul>

<h3 id="class-IO-label-Creating">Creating<span><a href="#class-IO-label-Creating">&para;</a> <a href="#top">&uarr;</a></span></h3>
<ul><li>
<p><a href="IO.html#method-c-new"><code>::new</code></a> (aliased as <a href="IO.html#method-c-for_fd"><code>::for_fd</code></a>): Creates and returns a new IO object for the given integer file descriptor.</p>
</li><li>
<p><a href="IO.html#method-c-open"><code>::open</code></a>: Creates a new IO object.</p>
</li><li>
<p><a href="IO.html#method-c-pipe"><code>::pipe</code></a>: Creates a connected pair of reader and writer IO objects.</p>
</li><li>
<p><a href="IO.html#method-c-popen"><code>::popen</code></a>: Creates an IO object to interact with a subprocess.</p>
</li><li>
<p><a href="IO.html#method-c-select"><code>::select</code></a>: Selects which given IO instances are ready for reading, writing, or have pending exceptions.</p>
</li></ul>

<h3 id="class-IO-label-Reading">Reading<span><a href="#class-IO-label-Reading">&para;</a> <a href="#top">&uarr;</a></span></h3>
<ul><li>
<p><a href="IO.html#method-c-binread"><code>::binread</code></a>: Returns a binary string with all or a subset of bytes from the given file.</p>
</li><li>
<p><a href="IO.html#method-c-read"><code>::read</code></a>: Returns a string with all or a subset of bytes from the given file.</p>
</li><li>
<p><a href="IO.html#method-c-readlines"><code>::readlines</code></a>: Returns an array of strings, which are the lines from the given file.</p>
</li><li>
<p><a href="IO.html#method-i-getbyte"><code>getbyte</code></a>: Returns the next 8-bit byte read from <code>self</code> as an integer.</p>
</li><li>
<p><a href="IO.html#method-i-getc"><code>getc</code></a>: Returns the next character read from <code>self</code> as a string.</p>
</li><li>
<p><a href="IO.html#method-i-gets"><code>gets</code></a>: Returns the line read from <code>self</code>.</p>
</li><li>
<p><a href="IO.html#method-i-pread"><code>pread</code></a>: Returns all or the next <em>n</em> bytes read from <code>self</code>, not updating the receiver’s offset.</p>
</li><li>
<p><a href="IO.html#method-i-read"><code>read</code></a>: Returns all remaining or the next <em>n</em> bytes read from <code>self</code> for a given <em>n</em>.</p>
</li><li>
<p><a href="IO.html#method-i-read_nonblock"><code>read_nonblock</code></a>: the next <em>n</em> bytes read from <code>self</code> for a given <em>n</em>, in non-block mode.</p>
</li><li>
<p><a href="IO.html#method-i-readbyte"><code>readbyte</code></a>: Returns the next byte read from <code>self</code>; same as <a href="IO.html#method-i-getbyte"><code>getbyte</code></a>, but raises an exception on end-of-stream.</p>
</li><li>
<p><a href="IO.html#method-i-readchar"><code>readchar</code></a>: Returns the next character read from <code>self</code>; same as <a href="IO.html#method-i-getc"><code>getc</code></a>, but raises an exception on end-of-stream.</p>
</li><li>
<p><a href="IO.html#method-i-readline"><code>readline</code></a>: Returns the next line read from <code>self</code>; same as getline, but raises an exception of end-of-stream.</p>
</li><li>
<p><a href="IO.html#method-i-readlines"><code>readlines</code></a>: Returns an array of all lines read read from <code>self</code>.</p>
</li><li>
<p><a href="IO.html#method-i-readpartial"><code>readpartial</code></a>: Returns up to the given number of bytes from <code>self</code>.</p>
</li></ul>

<h3 id="class-IO-label-Writing">Writing<span><a href="#class-IO-label-Writing">&para;</a> <a href="#top">&uarr;</a></span></h3>
<ul><li>
<p><a href="IO.html#method-c-binwrite"><code>::binwrite</code></a>: Writes the given string to the file at the given filepath, in binary mode.</p>
</li><li>
<p><a href="IO.html#method-c-write"><code>::write</code></a>: Writes the given string to <code>self</code>.</p>
</li><li>
<p><a href="IO.html#method-i-3C-3C"><code>&lt;&lt;</code></a>: Appends the given string to <code>self</code>.</p>
</li><li>
<p><a href="IO.html#method-i-print"><code>print</code></a>: Prints last read line or given objects to <code>self</code>.</p>
</li><li>
<p><a href="IO.html#method-i-printf"><code>printf</code></a>: Writes to <code>self</code> based on the given format string and objects.</p>
</li><li>
<p><a href="IO.html#method-i-putc"><code>putc</code></a>: Writes a character to <code>self</code>.</p>
</li><li>
<p><a href="IO.html#method-i-puts"><code>puts</code></a>: Writes lines to <code>self</code>, making sure line ends with a newline.</p>
</li><li>
<p><a href="IO.html#method-i-pwrite"><code>pwrite</code></a>: Writes the given string at the given offset, not updating the receiver’s offset.</p>
</li><li>
<p><a href="IO.html#method-i-write"><code>write</code></a>: Writes one or more given strings to <code>self</code>.</p>
</li><li>
<p><a href="IO.html#method-i-write_nonblock"><code>write_nonblock</code></a>: Writes one or more given strings to <code>self</code> in non-blocking mode.</p>
</li></ul>

<h3 id="class-IO-label-Positioning">Positioning<span><a href="#class-IO-label-Positioning">&para;</a> <a href="#top">&uarr;</a></span></h3>
<ul><li>
<p><a href="IO.html#method-i-lineno"><code>lineno</code></a>: Returns the current line number in <code>self</code>.</p>
</li><li>
<p><a href="IO.html#method-i-lineno-3D"><code>lineno=</code></a>: Sets the line number is <code>self</code>.</p>
</li><li>
<p><a href="IO.html#method-i-pos"><code>pos</code></a> (aliased as <a href="IO.html#method-i-tell"><code>tell</code></a>): Returns the current byte offset in <code>self</code>.</p>
</li><li>
<p><a href="IO.html#method-i-pos-3D"><code>pos=</code></a>: Sets the byte offset in <code>self</code>.</p>
</li><li>
<p><a href="IO.html#method-i-reopen"><code>reopen</code></a>: Reassociates <code>self</code> with a new or existing IO stream.</p>
</li><li>
<p><a href="IO.html#method-i-rewind"><code>rewind</code></a>: Positions <code>self</code> to the beginning of input.</p>
</li><li>
<p><a href="IO.html#method-i-seek"><code>seek</code></a>: Sets the offset for <code>self</code> relative to given position.</p>
</li></ul>

<h3 id="class-IO-label-Iterating">Iterating<span><a href="#class-IO-label-Iterating">&para;</a> <a href="#top">&uarr;</a></span></h3>
<ul><li>
<p><a href="IO.html#method-c-foreach"><code>::foreach</code></a>: Yields each line of given file to the block.</p>
</li><li>
<p><a href="IO.html#method-i-each"><code>each</code></a> (aliased as <a href="IO.html#method-i-each_line"><code>each_line</code></a>): Calls the given block with each successive line in <code>self</code>.</p>
</li><li>
<p><a href="IO.html#method-i-each_byte"><code>each_byte</code></a>: Calls the given block with each successive byte in <code>self</code> as an integer.</p>
</li><li>
<p><a href="IO.html#method-i-each_char"><code>each_char</code></a>: Calls the given block with each successive character in <code>self</code> as a string.</p>
</li><li>
<p><a href="IO.html#method-i-each_codepoint"><code>each_codepoint</code></a>: Calls the given block with each successive codepoint in <code>self</code> as an integer.</p>
</li></ul>

<h3 id="class-IO-label-Settings">Settings<span><a href="#class-IO-label-Settings">&para;</a> <a href="#top">&uarr;</a></span></h3>
<ul><li>
<p><a href="IO.html#method-i-autoclose-3D"><code>autoclose=</code></a>: Sets whether <code>self</code> auto-closes.</p>
</li><li>
<p><a href="IO.html#method-i-binmode"><code>binmode</code></a>: Sets <code>self</code> to binary mode.</p>
</li><li>
<p><a href="IO.html#method-i-close"><code>close</code></a>: Closes <code>self</code>.</p>
</li><li>
<p><a href="IO.html#method-i-close_on_exec-3D"><code>close_on_exec=</code></a>: Sets the close-on-exec flag.</p>
</li><li>
<p><a href="IO.html#method-i-close_read"><code>close_read</code></a>: Closes <code>self</code> for reading.</p>
</li><li>
<p><a href="IO.html#method-i-close_write"><code>close_write</code></a>: Closes <code>self</code> for writing.</p>
</li><li>
<p><a href="IO.html#method-i-set_encoding"><code>set_encoding</code></a>: Sets the encoding for <code>self</code>.</p>
</li><li>
<p><a href="IO.html#method-i-set_encoding_by_bom"><code>set_encoding_by_bom</code></a>: Sets the encoding for <code>self</code>, based on its Unicode byte-order-mark.</p>
</li><li>
<p><a href="IO.html#method-i-sync-3D"><code>sync=</code></a>: Sets the sync-mode to the given value.</p>
</li></ul>

<h3 id="class-IO-label-Querying">Querying<span><a href="#class-IO-label-Querying">&para;</a> <a href="#top">&uarr;</a></span></h3>
<ul><li>
<p><a href="IO.html#method-i-autoclose-3F"><code>autoclose?</code></a>: Returns whether <code>self</code> auto-closes.</p>
</li><li>
<p><a href="IO.html#method-i-binmode-3F"><code>binmode?</code></a>: Returns whether <code>self</code> is in binary mode.</p>
</li><li>
<p><a href="IO.html#method-i-close_on_exec-3F"><code>close_on_exec?</code></a>: Returns the close-on-exec flag for <code>self</code>.</p>
</li><li>
<p><a href="IO.html#method-i-closed-3F"><code>closed?</code></a>: Returns whether <code>self</code> is closed.</p>
</li><li>
<p><a href="IO.html#method-i-eof-3F"><code>eof?</code></a> (aliased as <a href="IO.html#method-i-eof"><code>eof</code></a>): Returns whether <code>self</code> is at end-of-stream.</p>
</li><li>
<p><a href="IO.html#method-i-external_encoding"><code>external_encoding</code></a>: Returns the external encoding object for <code>self</code>.</p>
</li><li>
<p><a href="IO.html#method-i-fileno"><code>fileno</code></a> (aliased as <a href="IO.html#method-i-to_i"><code>to_i</code></a>): Returns the integer file descriptor for <code>self</code></p>
</li><li>
<p><a href="IO.html#method-i-internal_encoding"><code>internal_encoding</code></a>: Returns the internal encoding object for <code>self</code>.</p>
</li><li>
<p><a href="IO.html#method-i-pid"><code>pid</code></a>: Returns the process ID of a child process associated with <code>self</code>, if <code>self</code> was created by <a href="IO.html#method-c-popen"><code>::popen</code></a>.</p>
</li><li>
<p><a href="IO.html#method-i-stat"><code>stat</code></a>: Returns the <a href="File/Stat.html"><code>File::Stat</code></a> object containing status information for <code>self</code>.</p>
</li><li>
<p><a href="IO.html#method-i-sync"><code>sync</code></a>: Returns whether <code>self</code> is in sync-mode.</p>
</li><li>
<p><a href="IO.html#method-i-tty-3F"><code>tty?</code></a> (aliased as <a href="IO.html#method-i-isatty"><code>isatty</code></a>): Returns whether <code>self</code> is a terminal.</p>
</li></ul>

<h3 id="class-IO-label-Buffering">Buffering<span><a href="#class-IO-label-Buffering">&para;</a> <a href="#top">&uarr;</a></span></h3>
<ul><li>
<p><a href="IO.html#method-i-fdatasync"><code>fdatasync</code></a>: Immediately writes all buffered data in <code>self</code> to disk.</p>
</li><li>
<p><a href="IO.html#method-i-flush"><code>flush</code></a>: Flushes any buffered data within <code>self</code> to the underlying operating system.</p>
</li><li>
<p><a href="IO.html#method-i-fsync"><code>fsync</code></a>: Immediately writes all buffered data and attributes in <code>self</code> to disk.</p>
</li><li>
<p><a href="IO.html#method-i-ungetbyte"><code>ungetbyte</code></a>: Prepends buffer for <code>self</code> with given integer byte or string.</p>
</li><li>
<p><a href="IO.html#method-i-ungetc"><code>ungetc</code></a>: Prepends buffer for <code>self</code> with given string.</p>
</li></ul>

<h3 id="class-IO-label-Low-Level+Access">Low-Level Access<span><a href="#class-IO-label-Low-Level+Access">&para;</a> <a href="#top">&uarr;</a></span></h3>
<ul><li>
<p><a href="IO.html#method-c-sysopen"><code>::sysopen</code></a>: Opens the file given by its path, returning the integer file descriptor.</p>
</li><li>
<p><a href="IO.html#method-i-advise"><code>advise</code></a>: Announces the intention to access data from <code>self</code> in a specific way.</p>
</li><li>
<p><a href="IO.html#method-i-fcntl"><code>fcntl</code></a>: Passes a low-level command to the file specified by the given file descriptor.</p>
</li><li>
<p><a href="IO.html#method-i-ioctl"><code>ioctl</code></a>: Passes a low-level command to the device specified by the given file descriptor.</p>
</li><li>
<p><a href="IO.html#method-i-sysread"><code>sysread</code></a>: Returns up to the next <em>n</em> bytes read from self using a low-level read.</p>
</li><li>
<p><a href="IO.html#method-i-sysseek"><code>sysseek</code></a>: Sets the offset for <code>self</code>.</p>
</li><li>
<p><a href="IO.html#method-i-syswrite"><code>syswrite</code></a>: Writes the given string to <code>self</code> using a low-level write.</p>
</li></ul>

<h3 id="class-IO-label-Other">Other<span><a href="#class-IO-label-Other">&para;</a> <a href="#top">&uarr;</a></span></h3>
<ul><li>
<p><a href="IO.html#method-c-copy_stream"><code>::copy_stream</code></a>: Copies data from a source to a destination, each of which is a filepath or an IO-like object.</p>
</li><li>
<p><a href="IO.html#method-c-try_convert"><code>::try_convert</code></a>: Returns a new IO object resulting from converting the given object.</p>
</li><li>
<p><a href="IO.html#method-i-inspect"><code>inspect</code></a>: Returns the string representation of <code>self</code>.</p>
</li></ul>

    </section>

      <section id="5Buntitled-5D" class="documentation-section">


      <section class="constants-list">
      <header>
      <h3>Constants</h3>
      </header>
      <dl>
          <dt id="EWOULDBLOCKWaitReadable">EWOULDBLOCKWaitReadable
          <dd><p><a href="IO/EAGAINWaitReadable.html"><code>EAGAINWaitReadable</code></a></p>
          <dt id="EWOULDBLOCKWaitWritable">EWOULDBLOCKWaitWritable
          <dd><p><a href="IO/EAGAINWaitWritable.html"><code>EAGAINWaitWritable</code></a></p>
          <dt id="PRIORITY">PRIORITY
          <dd>
          <dt id="READABLE">READABLE
          <dd>
          <dt id="SEEK_CUR">SEEK_CUR
          <dd><p>Set I/O position from the current position</p>
          <dt id="SEEK_DATA">SEEK_DATA
          <dd><p>Set I/O position to the next location containing data</p>
          <dt id="SEEK_END">SEEK_END
          <dd><p>Set I/O position from the end</p>
          <dt id="SEEK_HOLE">SEEK_HOLE
          <dd><p>Set I/O position to the next hole</p>
          <dt id="SEEK_SET">SEEK_SET
          <dd><p>Set I/O position from the beginning</p>
          <dt id="WRITABLE">WRITABLE
          <dd>
        </dl>
        </section>



                <section id="public-class-5Buntitled-5D-method-details" class="method-section">
                <header>
                <h3>Public Class Methods</h3>
                </header>

                  <div id="method-c-binread" class="method-detail ">
                      <div class="method-heading">
                        <span class="method-callseq">
                          binread(path, length = nil, offset = 0)    &rarr; string or nil
                              </span>
                              <span class="method-click-advice">click to toggle source</span>
                            </div>

                            <div class="method-description">
                              <p>Behaves like <a href="IO.html#method-c-read"><code>IO.read</code></a>, except that the stream is opened in binary mode with ASCII-8BIT encoding.</p>

<p>When called from class IO (but not subclasses of IO), this method has potential security vulnerabilities if called with untrusted input; see <a href="command_injection_rdoc.html">Command Injection</a>.</p>

                              <div class="method-source-code" id="binread-source">
            <pre>static VALUE
rb_io_s_binread(int argc, VALUE *argv, VALUE io)
{
    VALUE offset;
    struct foreach_arg arg;
    enum {
        fmode = FMODE_READABLE|FMODE_BINMODE,
        oflags = O_RDONLY
#ifdef O_BINARY
                |O_BINARY
#endif
    };
    struct rb_io_encoding convconfig = {NULL, NULL, 0, Qnil};

    rb_scan_args(argc, argv, &quot;12&quot;, NULL, NULL, &amp;offset);
    FilePathValue(argv[0]);
    convconfig.enc = rb_ascii8bit_encoding();
    arg.io = rb_io_open_generic(io, argv[0], oflags, fmode, &amp;convconfig, 0);
    if (NIL_P(arg.io)) return Qnil;
    arg.argv = argv+1;
    arg.argc = (argc &gt; 1) ? 1 : 0;
    if (!NIL_P(offset)) {
        struct seek_arg sarg;
        int state = 0;
        sarg.io = arg.io;
        sarg.offset = offset;
        sarg.mode = SEEK_SET;
        rb_protect(seek_before_access, (VALUE)&amp;sarg, &amp;state);
        if (state) {
            rb_io_close(arg.io);
            rb_jump_tag(state);
        }
    }
    return rb_ensure(io_s_read, (VALUE)&amp;arg, rb_io_close, arg.io);
}</pre>
                              </div>
                            </div>


                          </div>

                  <div id="method-c-binwrite" class="method-detail ">
                      <div class="method-heading">
                        <span class="method-callseq">
                          binwrite(path, string, offset = 0)    &rarr; integer
                              </span>
                              <span class="method-click-advice">click to toggle source</span>
                            </div>

                            <div class="method-description">
                              <p>Behaves like <a href="IO.html#method-c-write"><code>IO.write</code></a>, except that the stream is opened in binary mode with ASCII-8BIT encoding.</p>

<p>When called from class IO (but not subclasses of IO), this method has potential security vulnerabilities if called with untrusted input; see <a href="command_injection_rdoc.html">Command Injection</a>.</p>

                              <div class="method-source-code" id="binwrite-source">
            <pre>static VALUE
rb_io_s_binwrite(int argc, VALUE *argv, VALUE io)
{
    return io_s_write(argc, argv, io, 1);
}</pre>
                              </div>
                            </div>


                          </div>

                  <div id="method-c-copy_stream" class="method-detail ">
                      <div class="method-heading">
                        <span class="method-callseq">
                          copy_stream(src, dst, src_length = nil, src_offset = 0) &rarr; integer
                              </span>
                              <span class="method-click-advice">click to toggle source</span>
                            </div>

                            <div class="method-description">
                              <p>Copies from the given <code>src</code> to the given <code>dst</code>, returning the number of bytes copied.</p>
<ul><li>
<p>The given <code>src</code> must be one of the following:</p>
<ul><li>
<p>The path to a readable file, from which source data is to be read.</p>
</li><li>
<p>An IO-like object, opened for reading and capable of responding to method <code>:readpartial</code> or method <code>:read</code>.</p>
</li></ul>
</li><li>
<p>The given <code>dst</code> must be one of the following:</p>
<ul><li>
<p>The path to a writable file, to which data is to be written.</p>
</li><li>
<p>An IO-like object, opened for writing and capable of responding to method <code>:write</code>.</p>
</li></ul>
</li></ul>

<p>The examples here use file <code>t.txt</code> as source:</p>

<pre class="ruby"><span class="ruby-constant">File</span>.<span class="ruby-identifier">read</span>(<span class="ruby-string">&#39;t.txt&#39;</span>)
<span class="ruby-comment"># =&gt; &quot;First line\nSecond line\n\nThird line\nFourth line\n&quot;</span>
<span class="ruby-constant">File</span>.<span class="ruby-identifier">read</span>(<span class="ruby-string">&#39;t.txt&#39;</span>).<span class="ruby-identifier">size</span> <span class="ruby-comment"># =&gt; 47</span>
</pre>

<p>If only arguments <code>src</code> and <code>dst</code> are given, the entire source stream is copied:</p>

<pre class="ruby"><span class="ruby-comment"># Paths.</span>
<span class="ruby-constant">IO</span>.<span class="ruby-identifier">copy_stream</span>(<span class="ruby-string">&#39;t.txt&#39;</span>, <span class="ruby-string">&#39;t.tmp&#39;</span>)  <span class="ruby-comment"># =&gt; 47</span>

<span class="ruby-comment"># IOs (recall that a File is also an IO).</span>
<span class="ruby-identifier">src_io</span> = <span class="ruby-constant">File</span>.<span class="ruby-identifier">open</span>(<span class="ruby-string">&#39;t.txt&#39;</span>, <span class="ruby-string">&#39;r&#39;</span>) <span class="ruby-comment"># =&gt; #&lt;File:t.txt&gt;</span>
<span class="ruby-identifier">dst_io</span> = <span class="ruby-constant">File</span>.<span class="ruby-identifier">open</span>(<span class="ruby-string">&#39;t.tmp&#39;</span>, <span class="ruby-string">&#39;w&#39;</span>) <span class="ruby-comment"># =&gt; #&lt;File:t.tmp&gt;</span>
<span class="ruby-constant">IO</span>.<span class="ruby-identifier">copy_stream</span>(<span class="ruby-identifier">src_io</span>, <span class="ruby-identifier">dst_io</span>)   <span class="ruby-comment"># =&gt; 47</span>
<span class="ruby-identifier">src_io</span>.<span class="ruby-identifier">close</span>
<span class="ruby-identifier">dst_io</span>.<span class="ruby-identifier">close</span>
</pre>

<p>With argument <code>src_length</code> a non-negative integer, no more than that many bytes are copied:</p>

<pre class="ruby"><span class="ruby-constant">IO</span>.<span class="ruby-identifier">copy_stream</span>(<span class="ruby-string">&#39;t.txt&#39;</span>, <span class="ruby-string">&#39;t.tmp&#39;</span>, <span class="ruby-value">10</span>) <span class="ruby-comment"># =&gt; 10</span>
<span class="ruby-constant">File</span>.<span class="ruby-identifier">read</span>(<span class="ruby-string">&#39;t.tmp&#39;</span>)                   <span class="ruby-comment"># =&gt; &quot;First line&quot;</span>
</pre>

<p>With argument <code>src_offset</code> also given, the source stream is read beginning at that offset:</p>

<pre class="ruby"><span class="ruby-constant">IO</span>.<span class="ruby-identifier">copy_stream</span>(<span class="ruby-string">&#39;t.txt&#39;</span>, <span class="ruby-string">&#39;t.tmp&#39;</span>, <span class="ruby-value">11</span>, <span class="ruby-value">11</span>) <span class="ruby-comment"># =&gt; 11</span>
<span class="ruby-constant">IO</span>.<span class="ruby-identifier">read</span>(<span class="ruby-string">&#39;t.tmp&#39;</span>)                         <span class="ruby-comment"># =&gt; &quot;Second line&quot;</span>
</pre>

                              <div class="method-source-code" id="copy_stream-source">
            <pre>static VALUE
rb_io_s_copy_stream(int argc, VALUE *argv, VALUE io)
{
    VALUE src, dst, length, src_offset;
    struct copy_stream_struct st;

    MEMZERO(&amp;st, struct copy_stream_struct, 1);

    rb_scan_args(argc, argv, &quot;22&quot;, &amp;src, &amp;dst, &amp;length, &amp;src_offset);

    st.src = src;
    st.dst = dst;

    st.src_fptr = NULL;
    st.dst_fptr = NULL;

    if (NIL_P(length))
        st.copy_length = (rb_off_t)-1;
    else
        st.copy_length = NUM2OFFT(length);

    if (NIL_P(src_offset))
        st.src_offset = (rb_off_t)-1;
    else
        st.src_offset = NUM2OFFT(src_offset);

    rb_ensure(copy_stream_body, (VALUE)&amp;st, copy_stream_finalize, (VALUE)&amp;st);

    return OFFT2NUM(st.total);
}</pre>
                              </div>
                            </div>


                          </div>

                  <div id="method-c-for_fd" class="method-detail ">
                      <div class="method-heading">
                        <span class="method-callseq">
                          for_fd(fd, mode = &#39;r&#39;, **opts) &rarr; io
                              </span>
                              <span class="method-click-advice">click to toggle source</span>
                            </div>

                            <div class="method-description">
                              <p>Synonym for <a href="IO.html#method-c-new"><code>IO.new</code></a>.</p>

                              <div class="method-source-code" id="for_fd-source">
            <pre>static VALUE
rb_io_s_for_fd(int argc, VALUE *argv, VALUE klass)
{
    VALUE io = rb_obj_alloc(klass);
    rb_io_initialize(argc, argv, io);
    return io;
}</pre>
                              </div>
                            </div>


                          </div>

                  <div id="method-c-foreach" class="method-detail ">
                      <div class="method-heading">
                        <span class="method-callseq">
                          foreach(path, sep = $/, **opts) {|line| block }       &rarr; nil
                              </span>
                              <span class="method-click-advice">click to toggle source</span>
                            </div>
                      <div class="method-heading">
                        <span class="method-callseq">
                          foreach(path, limit, **opts) {|line| block }          &rarr; nil
                              </span>
                            </div>
                      <div class="method-heading">
                        <span class="method-callseq">
                          foreach(path, sep, limit, **opts) {|line| block }     &rarr; nil
                              </span>
                            </div>
                      <div class="method-heading">
                        <span class="method-callseq">
                          foreach(...)                                          &rarr; an_enumerator
                              </span>
                            </div>

                            <div class="method-description">
                              <p>Calls the block with each successive line read from the stream.</p>

<p>When called from class IO (but not subclasses of IO), this method has potential security vulnerabilities if called with untrusted input; see <a href="command_injection_rdoc.html">Command Injection</a>.</p>

<p>The first argument must be a string that is the path to a file.</p>

<p>With only argument <code>path</code> given, parses lines from the file at the given <code>path</code>, as determined by the default line separator, and calls the block with each successive line:</p>

<pre class="ruby"><span class="ruby-constant">File</span>.<span class="ruby-identifier">foreach</span>(<span class="ruby-string">&#39;t.txt&#39;</span>) {<span class="ruby-operator">|</span><span class="ruby-identifier">line</span><span class="ruby-operator">|</span> <span class="ruby-identifier">p</span> <span class="ruby-identifier">line</span> }
</pre>

<p>Output: the same as above.</p>

<p>For both forms, command and path, the remaining arguments are the same.</p>

<p>With argument <code>sep</code> given, parses lines as determined by that line separator (see <a href="IO.html#class-IO-label-Line+Separator">Line Separator</a>):</p>

<pre class="ruby"><span class="ruby-constant">File</span>.<span class="ruby-identifier">foreach</span>(<span class="ruby-string">&#39;t.txt&#39;</span>, <span class="ruby-string">&#39;li&#39;</span>) {<span class="ruby-operator">|</span><span class="ruby-identifier">line</span><span class="ruby-operator">|</span> <span class="ruby-identifier">p</span> <span class="ruby-identifier">line</span> }
</pre>

<p>Output:</p>

<pre class="ruby"><span class="ruby-string">&quot;First li&quot;</span>
<span class="ruby-string">&quot;ne\nSecond li&quot;</span>
<span class="ruby-string">&quot;ne\n\nThird li&quot;</span>
<span class="ruby-string">&quot;ne\nFourth li&quot;</span>
<span class="ruby-string">&quot;ne\n&quot;</span>
</pre>

<p>Each paragraph:</p>

<pre class="ruby"><span class="ruby-constant">File</span>.<span class="ruby-identifier">foreach</span>(<span class="ruby-string">&#39;t.txt&#39;</span>, <span class="ruby-string">&#39;&#39;</span>) {<span class="ruby-operator">|</span><span class="ruby-identifier">paragraph</span><span class="ruby-operator">|</span> <span class="ruby-identifier">p</span> <span class="ruby-identifier">paragraph</span> }
</pre>

<p>Output:</p>

<pre class="ruby"><span class="ruby-string">&quot;First line\nSecond line\n\n&quot;</span>
<span class="ruby-string">&quot;Third line\nFourth line\n&quot;</span>
</pre>

<p>With argument <code>limit</code> given, parses lines as determined by the default line separator and the given line-length limit (see <a href="IO.html#class-IO-label-Line+Limit">Line Limit</a>):</p>

<pre class="ruby"><span class="ruby-constant">File</span>.<span class="ruby-identifier">foreach</span>(<span class="ruby-string">&#39;t.txt&#39;</span>, <span class="ruby-value">7</span>) {<span class="ruby-operator">|</span><span class="ruby-identifier">line</span><span class="ruby-operator">|</span> <span class="ruby-identifier">p</span> <span class="ruby-identifier">line</span> }
</pre>

<p>Output:</p>

<pre class="ruby"><span class="ruby-string">&quot;First l&quot;</span>
<span class="ruby-string">&quot;ine\n&quot;</span>
<span class="ruby-string">&quot;Second &quot;</span>
<span class="ruby-string">&quot;line\n&quot;</span>
<span class="ruby-string">&quot;\n&quot;</span>
<span class="ruby-string">&quot;Third l&quot;</span>
<span class="ruby-string">&quot;ine\n&quot;</span>
<span class="ruby-string">&quot;Fourth l&quot;</span>
<span class="ruby-string">&quot;line\n&quot;</span>
</pre>

<p>With arguments <code>sep</code> and  <code>limit</code> given, parses lines as determined by the given line separator and the given line-length limit (see <a href="IO.html#class-IO-label-Line+Separator+and+Line+Limit">Line Separator and Line Limit</a>):</p>

<p>Optional keyword arguments <code>opts</code> specify:</p>
<ul><li>
<p><a href="IO.html#class-IO-label-Open+Options">Open Options</a>.</p>
</li><li>
<p><a href="encodings_rdoc.html#label-Encoding+Options">Encoding options</a>.</p>
</li><li>
<p><a href="IO.html#class-IO-label-Line+IO">Line Options</a>.</p>
</li></ul>

<p>Returns an <a href="Enumerator.html"><code>Enumerator</code></a> if no block is given.</p>

                              <div class="method-source-code" id="foreach-source">
            <pre>static VALUE
rb_io_s_foreach(int argc, VALUE *argv, VALUE self)
{
    VALUE opt;
    int orig_argc = argc;
    struct foreach_arg arg;
    struct getline_arg garg;

    argc = rb_scan_args(argc, argv, &quot;12:&quot;, NULL, NULL, NULL, &amp;opt);
    RETURN_ENUMERATOR(self, orig_argc, argv);
    extract_getline_args(argc-1, argv+1, &amp;garg);
    open_key_args(self, argc, argv, opt, &amp;arg);
    if (NIL_P(arg.io)) return Qnil;
    extract_getline_opts(opt, &amp;garg);
    check_getline_args(&amp;garg.rs, &amp;garg.limit, garg.io = arg.io);
    return rb_ensure(io_s_foreach, (VALUE)&amp;garg, rb_io_close, arg.io);
}</pre>
                              </div>
                            </div>


                          </div>

                  <div id="method-c-new" class="method-detail ">
                      <div class="method-heading">
                        <span class="method-callseq">
                          new(fd, mode = &#39;r&#39;, **opts) &rarr; io
                              </span>
                              <span class="method-click-advice">click to toggle source</span>
                            </div>

                            <div class="method-description">
                              <p>Creates and returns a new IO object (file stream) from a file descriptor.</p>

<p>IO.new may be useful for interaction with low-level libraries. For higher-level interactions, it may be simpler to create the file stream using <a href="File.html#method-c-open"><code>File.open</code></a>.</p>

<p>Argument <code>fd</code> must be a valid file descriptor (integer):</p>

<pre class="ruby"><span class="ruby-identifier">path</span> = <span class="ruby-string">&#39;t.tmp&#39;</span>
<span class="ruby-identifier">fd</span> = <span class="ruby-constant">IO</span>.<span class="ruby-identifier">sysopen</span>(<span class="ruby-identifier">path</span>) <span class="ruby-comment"># =&gt; 3</span>
<span class="ruby-constant">IO</span>.<span class="ruby-identifier">new</span>(<span class="ruby-identifier">fd</span>)            <span class="ruby-comment"># =&gt; #&lt;IO:fd 3&gt;</span>
</pre>

<p>The new IO object does not inherit encoding (because the integer file descriptor does not have an encoding):</p>

<pre class="ruby"><span class="ruby-identifier">fd</span> = <span class="ruby-constant">IO</span>.<span class="ruby-identifier">sysopen</span>(<span class="ruby-string">&#39;t.rus&#39;</span>, <span class="ruby-string">&#39;rb&#39;</span>)
<span class="ruby-identifier">io</span> = <span class="ruby-constant">IO</span>.<span class="ruby-identifier">new</span>(<span class="ruby-identifier">fd</span>)
<span class="ruby-identifier">io</span>.<span class="ruby-identifier">external_encoding</span> <span class="ruby-comment"># =&gt; #&lt;Encoding:UTF-8&gt; # Not ASCII-8BIT.</span>
</pre>

<p>Optional argument <code>mode</code> (defaults to ‘r’) must specify a valid mode; see <a href="File.html#class-File-label-Access+Modes">Access Modes</a>:</p>

<pre class="ruby"><span class="ruby-constant">IO</span>.<span class="ruby-identifier">new</span>(<span class="ruby-identifier">fd</span>, <span class="ruby-string">&#39;w&#39;</span>)         <span class="ruby-comment"># =&gt; #&lt;IO:fd 3&gt;</span>
<span class="ruby-constant">IO</span>.<span class="ruby-identifier">new</span>(<span class="ruby-identifier">fd</span>, <span class="ruby-constant">File</span><span class="ruby-operator">::</span><span class="ruby-constant">WRONLY</span>) <span class="ruby-comment"># =&gt; #&lt;IO:fd 3&gt;</span>
</pre>

<p>Optional keyword arguments <code>opts</code> specify:</p>
<ul><li>
<p><a href="IO.html#class-IO-label-Open+Options">Open Options</a>.</p>
</li><li>
<p><a href="encodings_rdoc.html#label-Encoding+Options">Encoding options</a>.</p>
</li></ul>

<p>Examples:</p>

<pre class="ruby"><span class="ruby-constant">IO</span>.<span class="ruby-identifier">new</span>(<span class="ruby-identifier">fd</span>, <span class="ruby-value">internal_encoding:</span> <span class="ruby-keyword">nil</span>) <span class="ruby-comment"># =&gt; #&lt;IO:fd 3&gt;</span>
<span class="ruby-constant">IO</span>.<span class="ruby-identifier">new</span>(<span class="ruby-identifier">fd</span>, <span class="ruby-value">autoclose:</span> <span class="ruby-keyword">true</span>)        <span class="ruby-comment"># =&gt; #&lt;IO:fd 3&gt;</span>
</pre>

                              <div class="method-source-code" id="new-source">
            <pre>static VALUE
rb_io_initialize(int argc, VALUE *argv, VALUE io)
{
    VALUE fnum, vmode;
    rb_io_t *fp;
    int fd, fmode, oflags = O_RDONLY;
    struct rb_io_encoding convconfig;
    VALUE opt;
#if defined(HAVE_FCNTL) &amp;&amp; defined(F_GETFL)
    int ofmode;
#else
    struct stat st;
#endif


    argc = rb_scan_args(argc, argv, &quot;11:&quot;, &amp;fnum, &amp;vmode, &amp;opt);
    rb_io_extract_modeenc(&amp;vmode, 0, opt, &amp;oflags, &amp;fmode, &amp;convconfig);

    fd = NUM2INT(fnum);
    if (rb_reserved_fd_p(fd)) {
        rb_raise(rb_eArgError, &quot;The given fd is not accessible because RubyVM reserves it&quot;);
    }
#if defined(HAVE_FCNTL) &amp;&amp; defined(F_GETFL)
    oflags = fcntl(fd, F_GETFL);
    if (oflags == -1) rb_sys_fail(0);
#else
    if (fstat(fd, &amp;st) &lt; 0) rb_sys_fail(0);
#endif
    rb_update_max_fd(fd);
#if defined(HAVE_FCNTL) &amp;&amp; defined(F_GETFL)
    ofmode = rb_io_oflags_fmode(oflags);
    if (NIL_P(vmode)) {
        fmode = ofmode;
    }
    else if ((~ofmode &amp; fmode) &amp; FMODE_READWRITE) {
        VALUE error = INT2FIX(EINVAL);
        rb_exc_raise(rb_class_new_instance(1, &amp;error, rb_eSystemCallError));
    }
#endif
    VALUE path = Qnil;

    if (!NIL_P(opt)) {
        if (rb_hash_aref(opt, sym_autoclose) == Qfalse) {
            fmode |= FMODE_EXTERNAL;
        }

        path = rb_hash_aref(opt, RB_ID2SYM(idPath));
        if (!NIL_P(path)) {
            StringValue(path);
            path = rb_str_new_frozen(path);
        }
    }

    MakeOpenFile(io, fp);
    fp-&gt;self = io;
    fp-&gt;fd = fd;
    fp-&gt;mode = fmode;
    fp-&gt;encs = convconfig;
    fp-&gt;pathv = path;
    fp-&gt;timeout = Qnil;
    clear_codeconv(fp);
    io_check_tty(fp);
    if (fileno(stdin) == fd)
        fp-&gt;stdio_file = stdin;
    else if (fileno(stdout) == fd)
        fp-&gt;stdio_file = stdout;
    else if (fileno(stderr) == fd)
        fp-&gt;stdio_file = stderr;

    if (fmode &amp; FMODE_SETENC_BY_BOM) io_set_encoding_by_bom(io);
    return io;
}</pre>
                              </div>
                            </div>


                          </div>

                  <div id="method-c-open" class="method-detail ">
                      <div class="method-heading">
                        <span class="method-callseq">
                          open(fd, mode = &#39;r&#39;, **opts)             &rarr; io
                              </span>
                              <span class="method-click-advice">click to toggle source</span>
                            </div>
                      <div class="method-heading">
                        <span class="method-callseq">
                          open(fd, mode = &#39;r&#39;, **opts) {|io| ... } &rarr; object
                              </span>
                            </div>

                            <div class="method-description">
                              <p>Creates a new IO object, via <a href="IO.html#method-c-new"><code>IO.new</code></a> with the given arguments.</p>

<p>With no block given, returns the IO object.</p>

<p>With a block given, calls the block with the IO object and returns the block’s value.</p>

                              <div class="method-source-code" id="open-source">
            <pre>static VALUE
rb_io_s_open(int argc, VALUE *argv, VALUE klass)
{
    VALUE io = rb_class_new_instance_kw(argc, argv, klass, RB_PASS_CALLED_KEYWORDS);

    if (rb_block_given_p()) {
        return rb_ensure(rb_yield, io, io_close, io);
    }

    return io;
}</pre>
                              </div>
                            </div>


                          </div>

                  <div id="method-c-pipe" class="method-detail ">
                      <div class="method-heading">
                        <span class="method-callseq">
                          pipe(**opts) &rarr; [read_io, write_io]
                              </span>
                              <span class="method-click-advice">click to toggle source</span>
                            </div>
                      <div class="method-heading">
                        <span class="method-callseq">
                          pipe(enc, **opts) &rarr; [read_io, write_io]
                              </span>
                            </div>
                      <div class="method-heading">
                        <span class="method-callseq">
                          pipe(ext_enc, int_enc, **opts) &rarr; [read_io, write_io]
                              </span>
                            </div>
                      <div class="method-heading">
                        <span class="method-callseq">
                          pipe(**opts) {|read_io, write_io| ...} &rarr; object
                              </span>
                            </div>
                      <div class="method-heading">
                        <span class="method-callseq">
                          pipe(enc, **opts) {|read_io, write_io| ...} &rarr; object
                              </span>
                            </div>
                      <div class="method-heading">
                        <span class="method-callseq">
                          pipe(ext_enc, int_enc, **opts) {|read_io, write_io| ...} &rarr; object
                              </span>
                            </div>

                            <div class="method-description">
                              <p>Creates a pair of pipe endpoints, <code>read_io</code> and <code>write_io</code>, connected to each other.</p>

<p>If argument <code>enc_string</code> is given, it must be a string containing one of:</p>
<ul><li>
<p>The name of the encoding to be used as the external encoding.</p>
</li><li>
<p>The colon-separated names of two encodings to be used as the external and internal encodings.</p>
</li></ul>

<p>If argument <code>int_enc</code> is given, it must be an <a href="Encoding.html"><code>Encoding</code></a> object or encoding name string that specifies the internal encoding to be used; if argument <code>ext_enc</code> is also given, it must be an <a href="Encoding.html"><code>Encoding</code></a> object or encoding name string that specifies the external encoding to be used.</p>

<p>The string read from <code>read_io</code> is tagged with the external encoding; if an internal encoding is also specified, the string is converted to, and tagged with, that encoding.</p>

<p>If any encoding is specified, optional hash arguments specify the conversion option.</p>

<p>Optional keyword arguments <code>opts</code> specify:</p>
<ul><li>
<p><a href="IO.html#class-IO-label-Open+Options">Open Options</a>.</p>
</li><li>
<p><a href="encodings_rdoc.html#label-Encoding+Options">Encoding Options</a>.</p>
</li></ul>

<p>With no block given, returns the two endpoints in an array:</p>

<pre class="ruby"><span class="ruby-constant">IO</span>.<span class="ruby-identifier">pipe</span> <span class="ruby-comment"># =&gt; [#&lt;IO:fd 4&gt;, #&lt;IO:fd 5&gt;]</span>
</pre>

<p>With a block given, calls the block with the two endpoints; closes both endpoints and returns the value of the block:</p>

<pre class="ruby"><span class="ruby-constant">IO</span>.<span class="ruby-identifier">pipe</span> {<span class="ruby-operator">|</span><span class="ruby-identifier">read_io</span>, <span class="ruby-identifier">write_io</span><span class="ruby-operator">|</span> <span class="ruby-identifier">p</span> <span class="ruby-identifier">read_io</span>; <span class="ruby-identifier">p</span> <span class="ruby-identifier">write_io</span> }
</pre>

<p>Output:</p>

<pre class="ruby"><span class="ruby-comment">#&lt;IO:fd 6&gt;</span>
<span class="ruby-comment">#&lt;IO:fd 7&gt;</span>
</pre>

<p>Not available on all platforms.</p>

<p>In the example below, the two processes close the ends of the pipe that they are not using. This is not just a cosmetic nicety. The read end of a pipe will not generate an end of file condition if there are any writers with the pipe still open. In the case of the parent process, the <code>rd.read</code> will never return if it does not first issue a <code>wr.close</code>:</p>

<pre class="ruby"><span class="ruby-identifier">rd</span>, <span class="ruby-identifier">wr</span> = <span class="ruby-constant">IO</span>.<span class="ruby-identifier">pipe</span>

<span class="ruby-keyword">if</span> <span class="ruby-identifier">fork</span>
  <span class="ruby-identifier">wr</span>.<span class="ruby-identifier">close</span>
  <span class="ruby-identifier">puts</span> <span class="ruby-node">&quot;Parent got: &lt;#{rd.read}&gt;&quot;</span>
  <span class="ruby-identifier">rd</span>.<span class="ruby-identifier">close</span>
  <span class="ruby-constant">Process</span>.<span class="ruby-identifier">wait</span>
<span class="ruby-keyword">else</span>
  <span class="ruby-identifier">rd</span>.<span class="ruby-identifier">close</span>
  <span class="ruby-identifier">puts</span> <span class="ruby-string">&#39;Sending message to parent&#39;</span>
  <span class="ruby-identifier">wr</span>.<span class="ruby-identifier">write</span> <span class="ruby-string">&quot;Hi Dad&quot;</span>
  <span class="ruby-identifier">wr</span>.<span class="ruby-identifier">close</span>
<span class="ruby-keyword">end</span>
</pre>

<p><em>produces:</em></p>

<pre>Sending message to parent
Parent got: &lt;Hi Dad&gt;</pre>

                              <div class="method-source-code" id="pipe-source">
            <pre>static VALUE
rb_io_s_pipe(int argc, VALUE *argv, VALUE klass)
{
    int pipes[2], state;
    VALUE r, w, args[3], v1, v2;
    VALUE opt;
    rb_io_t *fptr, *fptr2;
    struct io_encoding_set_args ies_args;
    int fmode = 0;
    VALUE ret;

    argc = rb_scan_args(argc, argv, &quot;02:&quot;, &amp;v1, &amp;v2, &amp;opt);
    if (rb_pipe(pipes) &lt; 0)
        rb_sys_fail(0);

    args[0] = klass;
    args[1] = INT2NUM(pipes[0]);
    args[2] = INT2FIX(O_RDONLY);
    r = rb_protect(io_new_instance, (VALUE)args, &amp;state);
    if (state) {
        close(pipes[0]);
        close(pipes[1]);
        rb_jump_tag(state);
    }
    GetOpenFile(r, fptr);

    ies_args.fptr = fptr;
    ies_args.v1 = v1;
    ies_args.v2 = v2;
    ies_args.opt = opt;
    rb_protect(io_encoding_set_v, (VALUE)&amp;ies_args, &amp;state);
    if (state) {
        close(pipes[1]);
        io_close(r);
        rb_jump_tag(state);
    }

    args[1] = INT2NUM(pipes[1]);
    args[2] = INT2FIX(O_WRONLY);
    w = rb_protect(io_new_instance, (VALUE)args, &amp;state);
    if (state) {
        close(pipes[1]);
        if (!NIL_P(r)) rb_io_close(r);
        rb_jump_tag(state);
    }
    GetOpenFile(w, fptr2);
    rb_io_synchronized(fptr2);

    extract_binmode(opt, &amp;fmode);

    if ((fmode &amp; FMODE_BINMODE) &amp;&amp; NIL_P(v1)) {
        rb_io_ascii8bit_binmode(r);
        rb_io_ascii8bit_binmode(w);
    }

#if DEFAULT_TEXTMODE
    if ((fptr-&gt;mode &amp; FMODE_TEXTMODE) &amp;&amp; (fmode &amp; FMODE_BINMODE)) {
        fptr-&gt;mode &amp;= ~FMODE_TEXTMODE;
        setmode(fptr-&gt;fd, O_BINARY);
    }
#if RUBY_CRLF_ENVIRONMENT
    if (fptr-&gt;encs.ecflags &amp; ECONV_DEFAULT_NEWLINE_DECORATOR) {
        fptr-&gt;encs.ecflags |= ECONV_UNIVERSAL_NEWLINE_DECORATOR;
    }
#endif
#endif
    fptr-&gt;mode |= fmode;
#if DEFAULT_TEXTMODE
    if ((fptr2-&gt;mode &amp; FMODE_TEXTMODE) &amp;&amp; (fmode &amp; FMODE_BINMODE)) {
        fptr2-&gt;mode &amp;= ~FMODE_TEXTMODE;
        setmode(fptr2-&gt;fd, O_BINARY);
    }
#endif
    fptr2-&gt;mode |= fmode;

    ret = rb_assoc_new(r, w);
    if (rb_block_given_p()) {
        VALUE rw[2];
        rw[0] = r;
        rw[1] = w;
        return rb_ensure(rb_yield, ret, pipe_pair_close, (VALUE)rw);
    }
    return ret;
}</pre>
                              </div>
                            </div>


                          </div>

                  <div id="method-c-popen" class="method-detail ">
                      <div class="method-heading">
                        <span class="method-callseq">
                          popen(env = {}, cmd, mode = &#39;r&#39;, **opts) &rarr; io
                              </span>
                              <span class="method-click-advice">click to toggle source</span>
                            </div>
                      <div class="method-heading">
                        <span class="method-callseq">
                          popen(env = {}, cmd, mode = &#39;r&#39;, **opts) {|io| ... } &rarr; object
                              </span>
                            </div>

                            <div class="method-description">
                              <p>Executes the given command <code>cmd</code> as a subprocess whose $stdin and $stdout are connected to a new stream <code>io</code>.</p>

<p>This method has potential security vulnerabilities if called with untrusted input; see <a href="command_injection_rdoc.html">Command Injection</a>.</p>

<p>If no block is given, returns the new stream, which depending on given <code>mode</code> may be open for reading, writing, or both. The stream should be explicitly closed (eventually) to avoid resource leaks.</p>

<p>If a block is given, the stream is passed to the block (again, open for reading, writing, or both); when the block exits, the stream is closed, and the block’s value is assigned to global variable <code>$?</code> and returned.</p>

<p>Optional argument <code>mode</code> may be any valid IO mode. See <a href="File.html#class-File-label-Access+Modes">Access Modes</a>.</p>

<p>Required argument <code>cmd</code> determines which of the following occurs:</p>
<ul><li>
<p>The process forks.</p>
</li><li>
<p>A specified program runs in a shell.</p>
</li><li>
<p>A specified program runs with specified arguments.</p>
</li><li>
<p>A specified program runs with specified arguments and a specified <code>argv0</code>.</p>
</li></ul>

<p>Each of these is detailed below.</p>

<p>The optional hash argument <code>env</code> specifies name/value pairs that are to be added to the environment variables for the subprocess:</p>

<pre class="ruby"><span class="ruby-constant">IO</span>.<span class="ruby-identifier">popen</span>({<span class="ruby-string">&#39;FOO&#39;</span> <span class="ruby-operator">=&gt;</span> <span class="ruby-string">&#39;bar&#39;</span>}, <span class="ruby-string">&#39;ruby&#39;</span>, <span class="ruby-string">&#39;r+&#39;</span>) <span class="ruby-keyword">do</span> <span class="ruby-operator">|</span><span class="ruby-identifier">pipe</span><span class="ruby-operator">|</span>
  <span class="ruby-identifier">pipe</span>.<span class="ruby-identifier">puts</span> <span class="ruby-string">&#39;puts ENV[&quot;FOO&quot;]&#39;</span>
  <span class="ruby-identifier">pipe</span>.<span class="ruby-identifier">close_write</span>
  <span class="ruby-identifier">pipe</span>.<span class="ruby-identifier">gets</span>
<span class="ruby-keyword">end</span> <span class="ruby-operator">=&gt;</span> <span class="ruby-string">&quot;bar\n&quot;</span>
</pre>

<p>Optional keyword arguments <code>opts</code> specify:</p>
<ul><li>
<p><a href="IO.html#class-IO-label-Open+Options">Open options</a>.</p>
</li><li>
<p><a href="encodings_rdoc.html#label-Encoding+Options">Encoding options</a>.</p>
</li><li>
<p>Options for <a href="Kernel.html#method-i-spawn"><code>Kernel#spawn</code></a>.</p>
</li></ul>

<p><strong>Forked Process</strong></p>

<p>When argument <code>cmd</code> is the 1-character string <code>&#39;-&#39;</code>, causes the process to fork:</p>

<pre class="ruby"><span class="ruby-constant">IO</span>.<span class="ruby-identifier">popen</span>(<span class="ruby-string">&#39;-&#39;</span>) <span class="ruby-keyword">do</span> <span class="ruby-operator">|</span><span class="ruby-identifier">pipe</span><span class="ruby-operator">|</span>
  <span class="ruby-keyword">if</span> <span class="ruby-identifier">pipe</span>
    <span class="ruby-identifier">$stderr</span>.<span class="ruby-identifier">puts</span> <span class="ruby-node">&quot;In parent, child pid is #{pipe.pid}\n&quot;</span>
  <span class="ruby-keyword">else</span>
    <span class="ruby-identifier">$stderr</span>.<span class="ruby-identifier">puts</span> <span class="ruby-node">&quot;In child, pid is #{$$}\n&quot;</span>
  <span class="ruby-keyword">end</span>
<span class="ruby-keyword">end</span>
</pre>

<p>Output:</p>

<pre>In parent, child pid is 26253
In child, pid is 26253</pre>

<p>Note that this is not supported on all platforms.</p>

<p><strong>Shell Subprocess</strong></p>

<p>When argument <code>cmd</code> is a single string (but not <code>&#39;-&#39;</code>), the program named <code>cmd</code> is run as a shell command:</p>

<pre class="ruby"><span class="ruby-constant">IO</span>.<span class="ruby-identifier">popen</span>(<span class="ruby-string">&#39;uname&#39;</span>) <span class="ruby-keyword">do</span> <span class="ruby-operator">|</span><span class="ruby-identifier">pipe</span><span class="ruby-operator">|</span>
  <span class="ruby-identifier">pipe</span>.<span class="ruby-identifier">readlines</span>
<span class="ruby-keyword">end</span>
</pre>

<p>Output:</p>

<pre class="ruby">[<span class="ruby-string">&quot;Linux\n&quot;</span>]
</pre>

<p>Another example:</p>

<pre class="ruby"><span class="ruby-constant">IO</span>.<span class="ruby-identifier">popen</span>(<span class="ruby-string">&#39;/bin/sh&#39;</span>, <span class="ruby-string">&#39;r+&#39;</span>) <span class="ruby-keyword">do</span> <span class="ruby-operator">|</span><span class="ruby-identifier">pipe</span><span class="ruby-operator">|</span>
  <span class="ruby-identifier">pipe</span>.<span class="ruby-identifier">puts</span>(<span class="ruby-string">&#39;ls&#39;</span>)
  <span class="ruby-identifier">pipe</span>.<span class="ruby-identifier">close_write</span>
  <span class="ruby-identifier">$stderr</span>.<span class="ruby-identifier">puts</span> <span class="ruby-identifier">pipe</span>.<span class="ruby-identifier">readlines</span>.<span class="ruby-identifier">size</span>
<span class="ruby-keyword">end</span>
</pre>

<p>Output:</p>

<pre class="ruby"><span class="ruby-value">213</span>
</pre>

<p><strong>Program Subprocess</strong></p>

<p>When argument <code>cmd</code> is an array of strings, the program named <code>cmd[0]</code> is run with all elements of <code>cmd</code> as its arguments:</p>

<pre class="ruby"><span class="ruby-constant">IO</span>.<span class="ruby-identifier">popen</span>([<span class="ruby-string">&#39;du&#39;</span>, <span class="ruby-string">&#39;..&#39;</span>, <span class="ruby-string">&#39;.&#39;</span>]) <span class="ruby-keyword">do</span> <span class="ruby-operator">|</span><span class="ruby-identifier">pipe</span><span class="ruby-operator">|</span>
  <span class="ruby-identifier">$stderr</span>.<span class="ruby-identifier">puts</span> <span class="ruby-identifier">pipe</span>.<span class="ruby-identifier">readlines</span>.<span class="ruby-identifier">size</span>
<span class="ruby-keyword">end</span>
</pre>

<p>Output:</p>

<pre class="ruby"><span class="ruby-value">1111</span>
</pre>

<p><strong>Program Subprocess with <code>argv0</code></strong></p>

<p>When argument <code>cmd</code> is an array whose first element is a 2-element string array and whose remaining elements (if any) are strings:</p>
<ul><li>
<p><code>cmd[0][0]</code> (the first string in the nested array) is the name of a program that is run.</p>
</li><li>
<p><code>cmd[0][1]</code> (the second string in the nested array) is set as the program’s <code>argv[0]</code>.</p>
</li><li>
<p><code>cmd[1..-1]</code> (the strings in the outer array) are the program’s arguments.</p>
</li></ul>

<p>Example (sets <code>$0</code> to ‘foo’):</p>

<pre class="ruby"><span class="ruby-constant">IO</span>.<span class="ruby-identifier">popen</span>([[<span class="ruby-string">&#39;/bin/sh&#39;</span>, <span class="ruby-string">&#39;foo&#39;</span>], <span class="ruby-string">&#39;-c&#39;</span>, <span class="ruby-string">&#39;echo $0&#39;</span>]).<span class="ruby-identifier">read</span> <span class="ruby-comment"># =&gt; &quot;foo\n&quot;</span>
</pre>

<p><strong>Some Special Examples</strong></p>

<pre class="ruby"><span class="ruby-comment"># Set IO encoding.</span>
<span class="ruby-constant">IO</span>.<span class="ruby-identifier">popen</span>(<span class="ruby-string">&quot;nkf -e filename&quot;</span>, <span class="ruby-value">:external_encoding</span><span class="ruby-operator">=&gt;</span><span class="ruby-string">&quot;EUC-JP&quot;</span>) {<span class="ruby-operator">|</span><span class="ruby-identifier">nkf_io</span><span class="ruby-operator">|</span>
  <span class="ruby-identifier">euc_jp_string</span> = <span class="ruby-identifier">nkf_io</span>.<span class="ruby-identifier">read</span>
}

<span class="ruby-comment"># Merge standard output and standard error using Kernel#spawn option. See Kernel#spawn.</span>
<span class="ruby-constant">IO</span>.<span class="ruby-identifier">popen</span>([<span class="ruby-string">&quot;ls&quot;</span>, <span class="ruby-string">&quot;/&quot;</span>, <span class="ruby-value">:err</span><span class="ruby-operator">=&gt;</span>[<span class="ruby-value">:child</span>, <span class="ruby-value">:out</span>]]) <span class="ruby-keyword">do</span> <span class="ruby-operator">|</span><span class="ruby-identifier">io</span><span class="ruby-operator">|</span>
  <span class="ruby-identifier">ls_result_with_error</span> = <span class="ruby-identifier">io</span>.<span class="ruby-identifier">read</span>
<span class="ruby-keyword">end</span>

<span class="ruby-comment"># Use mixture of spawn options and IO options.</span>
<span class="ruby-constant">IO</span>.<span class="ruby-identifier">popen</span>([<span class="ruby-string">&quot;ls&quot;</span>, <span class="ruby-string">&quot;/&quot;</span>], <span class="ruby-value">:err</span><span class="ruby-operator">=&gt;</span>[<span class="ruby-value">:child</span>, <span class="ruby-value">:out</span>]) <span class="ruby-keyword">do</span> <span class="ruby-operator">|</span><span class="ruby-identifier">io</span><span class="ruby-operator">|</span>
  <span class="ruby-identifier">ls_result_with_error</span> = <span class="ruby-identifier">io</span>.<span class="ruby-identifier">read</span>
<span class="ruby-keyword">end</span>

 <span class="ruby-identifier">f</span> = <span class="ruby-constant">IO</span>.<span class="ruby-identifier">popen</span>(<span class="ruby-string">&quot;uname&quot;</span>)
 <span class="ruby-identifier">p</span> <span class="ruby-identifier">f</span>.<span class="ruby-identifier">readlines</span>
 <span class="ruby-identifier">f</span>.<span class="ruby-identifier">close</span>
 <span class="ruby-identifier">puts</span> <span class="ruby-node">&quot;Parent is #{Process.pid}&quot;</span>
 <span class="ruby-constant">IO</span>.<span class="ruby-identifier">popen</span>(<span class="ruby-string">&quot;date&quot;</span>) {<span class="ruby-operator">|</span><span class="ruby-identifier">f</span><span class="ruby-operator">|</span> <span class="ruby-identifier">puts</span> <span class="ruby-identifier">f</span>.<span class="ruby-identifier">gets</span> }
 <span class="ruby-constant">IO</span>.<span class="ruby-identifier">popen</span>(<span class="ruby-string">&quot;-&quot;</span>) {<span class="ruby-operator">|</span><span class="ruby-identifier">f</span><span class="ruby-operator">|</span> <span class="ruby-identifier">$stderr</span>.<span class="ruby-identifier">puts</span> <span class="ruby-node">&quot;#{Process.pid} is here, f is #{f.inspect}&quot;</span>}
 <span class="ruby-identifier">p</span> <span class="ruby-identifier">$?</span>
 <span class="ruby-constant">IO</span>.<span class="ruby-identifier">popen</span>(<span class="ruby-node">%w&quot;sed -e s|^|&lt;foo&gt;| -e s&amp;$&amp;;zot;&amp;&quot;</span>, <span class="ruby-string">&quot;r+&quot;</span>) {<span class="ruby-operator">|</span><span class="ruby-identifier">f</span><span class="ruby-operator">|</span>
   <span class="ruby-identifier">f</span>.<span class="ruby-identifier">puts</span> <span class="ruby-string">&quot;bar&quot;</span>; <span class="ruby-identifier">f</span>.<span class="ruby-identifier">close_write</span>; <span class="ruby-identifier">puts</span> <span class="ruby-identifier">f</span>.<span class="ruby-identifier">gets</span>
 }
</pre>

<p>Output (from last section):</p>

<pre>[&quot;Linux\n&quot;]
Parent is 21346
Thu Jan 15 22:41:19 JST 2009
21346 is here, f is #&lt;IO:fd 3&gt;
21352 is here, f is nil
#&lt;Process::Status: pid 21352 exit 0&gt;
&lt;foo&gt;bar;zot;</pre>

<p>Raises exceptions that <a href="IO.html#method-c-pipe"><code>IO.pipe</code></a> and <a href="Kernel.html#method-i-spawn"><code>Kernel.spawn</code></a> raise.</p>

                              <div class="method-source-code" id="popen-source">
            <pre>static VALUE
rb_io_s_popen(int argc, VALUE *argv, VALUE klass)
{
    VALUE pname, pmode = Qnil, opt = Qnil, env = Qnil;

    if (argc &gt; 1 &amp;&amp; !NIL_P(opt = rb_check_hash_type(argv[argc-1]))) --argc;
    if (argc &gt; 1 &amp;&amp; !NIL_P(env = rb_check_hash_type(argv[0]))) --argc, ++argv;
    switch (argc) {
      case 2:
        pmode = argv[1];
      case 1:
        pname = argv[0];
        break;
      default:
        {
            int ex = !NIL_P(opt);
            rb_error_arity(argc + ex, 1 + ex, 2 + ex);
        }
    }
    return popen_finish(rb_io_popen(pname, pmode, env, opt), klass);
}</pre>
                              </div>
                            </div>


                          </div>

                  <div id="method-c-read" class="method-detail ">
                      <div class="method-heading">
                        <span class="method-callseq">
                          read(path, length = nil, offset = 0, **opts)    &rarr; string or nil
                              </span>
                              <span class="method-click-advice">click to toggle source</span>
                            </div>

                            <div class="method-description">
                              <p>Opens the stream, reads and returns some or all of its content, and closes the stream; returns <code>nil</code> if no bytes were read.</p>

<p>When called from class IO (but not subclasses of IO), this method has potential security vulnerabilities if called with untrusted input; see <a href="command_injection_rdoc.html">Command Injection</a>.</p>

<p>The first argument must be a string that is the path to a file.</p>

<p>With only argument <code>path</code> given, reads in text mode and returns the entire content of the file at the given path:</p>

<pre class="ruby"><span class="ruby-constant">IO</span>.<span class="ruby-identifier">read</span>(<span class="ruby-string">&#39;t.txt&#39;</span>)
<span class="ruby-comment"># =&gt; &quot;First line\nSecond line\n\nThird line\nFourth line\n&quot;</span>
</pre>

<p>On Windows, text mode can terminate reading and leave bytes in the file unread when encountering certain special bytes. Consider using <a href="IO.html#method-c-binread"><code>IO.binread</code></a> if all bytes in the file should be read.</p>

<p>With argument <code>length</code>, returns <code>length</code> bytes if available:</p>

<pre class="ruby"><span class="ruby-constant">IO</span>.<span class="ruby-identifier">read</span>(<span class="ruby-string">&#39;t.txt&#39;</span>, <span class="ruby-value">7</span>) <span class="ruby-comment"># =&gt; &quot;First l&quot;</span>
<span class="ruby-constant">IO</span>.<span class="ruby-identifier">read</span>(<span class="ruby-string">&#39;t.txt&#39;</span>, <span class="ruby-value">700</span>)
<span class="ruby-comment"># =&gt; &quot;First line\r\nSecond line\r\n\r\nFourth line\r\nFifth line\r\n&quot;</span>
</pre>

<p>With arguments <code>length</code> and <code>offset</code>, returns <code>length</code> bytes if available, beginning at the given <code>offset</code>:</p>

<pre class="ruby"><span class="ruby-constant">IO</span>.<span class="ruby-identifier">read</span>(<span class="ruby-string">&#39;t.txt&#39;</span>, <span class="ruby-value">10</span>, <span class="ruby-value">2</span>)   <span class="ruby-comment"># =&gt; &quot;rst line\nS&quot;</span>
<span class="ruby-constant">IO</span>.<span class="ruby-identifier">read</span>(<span class="ruby-string">&#39;t.txt&#39;</span>, <span class="ruby-value">10</span>, <span class="ruby-value">200</span>) <span class="ruby-comment"># =&gt; nil</span>
</pre>

<p>Optional keyword arguments <code>opts</code> specify:</p>
<ul><li>
<p><a href="IO.html#class-IO-label-Open+Options">Open Options</a>.</p>
</li><li>
<p><a href="encodings_rdoc.html#label-Encoding+Options">Encoding options</a>.</p>
</li></ul>

                              <div class="method-source-code" id="read-source">
            <pre>static VALUE
rb_io_s_read(int argc, VALUE *argv, VALUE io)
{
    VALUE opt, offset;
    long off;
    struct foreach_arg arg;

    argc = rb_scan_args(argc, argv, &quot;13:&quot;, NULL, NULL, &amp;offset, NULL, &amp;opt);
    if (!NIL_P(offset) &amp;&amp; (off = NUM2LONG(offset)) &lt; 0) {
        rb_raise(rb_eArgError, &quot;negative offset %ld given&quot;, off);
    }
    open_key_args(io, argc, argv, opt, &amp;arg);
    if (NIL_P(arg.io)) return Qnil;
    if (!NIL_P(offset)) {
        struct seek_arg sarg;
        int state = 0;
        sarg.io = arg.io;
        sarg.offset = offset;
        sarg.mode = SEEK_SET;
        rb_protect(seek_before_access, (VALUE)&amp;sarg, &amp;state);
        if (state) {
            rb_io_close(arg.io);
            rb_jump_tag(state);
        }
        if (arg.argc == 2) arg.argc = 1;
    }
    return rb_ensure(io_s_read, (VALUE)&amp;arg, rb_io_close, arg.io);
}</pre>
                              </div>
                            </div>


                          </div>

                  <div id="method-c-readlines" class="method-detail ">
                      <div class="method-heading">
                        <span class="method-callseq">
                          readlines(path, sep = $/, **opts)     &rarr; array
                              </span>
                              <span class="method-click-advice">click to toggle source</span>
                            </div>
                      <div class="method-heading">
                        <span class="method-callseq">
                          readlines(path, limit, **opts)      &rarr; array
                              </span>
                            </div>
                      <div class="method-heading">
                        <span class="method-callseq">
                          readlines(path, sep, limit, **opts) &rarr; array
                              </span>
                            </div>

                            <div class="method-description">
                              <p>Returns an array of all lines read from the stream.</p>

<p>When called from class IO (but not subclasses of IO), this method has potential security vulnerabilities if called with untrusted input; see <a href="command_injection_rdoc.html">Command Injection</a>.</p>

<p>The first argument must be a string that is the path to a file.</p>

<p>With only argument <code>path</code> given, parses lines from the file at the given <code>path</code>, as determined by the default line separator, and returns those lines in an array:</p>

<pre class="ruby"><span class="ruby-constant">IO</span>.<span class="ruby-identifier">readlines</span>(<span class="ruby-string">&#39;t.txt&#39;</span>)
<span class="ruby-comment"># =&gt; [&quot;First line\n&quot;, &quot;Second line\n&quot;, &quot;\n&quot;, &quot;Third line\n&quot;, &quot;Fourth line\n&quot;]</span>
</pre>

<p>With argument <code>sep</code> given, parses lines as determined by that line separator (see <a href="IO.html#class-IO-label-Line+Separator">Line Separator</a>):</p>

<pre class="ruby"><span class="ruby-comment"># Ordinary separator.</span>
<span class="ruby-constant">IO</span>.<span class="ruby-identifier">readlines</span>(<span class="ruby-string">&#39;t.txt&#39;</span>, <span class="ruby-string">&#39;li&#39;</span>)
<span class="ruby-comment"># =&gt;[&quot;First li&quot;, &quot;ne\nSecond li&quot;, &quot;ne\n\nThird li&quot;, &quot;ne\nFourth li&quot;, &quot;ne\n&quot;]</span>
<span class="ruby-comment"># Get-paragraphs separator.</span>
<span class="ruby-constant">IO</span>.<span class="ruby-identifier">readlines</span>(<span class="ruby-string">&#39;t.txt&#39;</span>, <span class="ruby-string">&#39;&#39;</span>)
<span class="ruby-comment"># =&gt; [&quot;First line\nSecond line\n\n&quot;, &quot;Third line\nFourth line\n&quot;]</span>
<span class="ruby-comment"># Get-all separator.</span>
<span class="ruby-constant">IO</span>.<span class="ruby-identifier">readlines</span>(<span class="ruby-string">&#39;t.txt&#39;</span>, <span class="ruby-keyword">nil</span>)
<span class="ruby-comment"># =&gt; [&quot;First line\nSecond line\n\nThird line\nFourth line\n&quot;]</span>
</pre>

<p>With argument <code>limit</code> given, parses lines as determined by the default line separator and the given line-length limit (see <a href="IO.html#class-IO-label-Line+Limit">Line Limit</a>):</p>

<pre class="ruby"><span class="ruby-constant">IO</span>.<span class="ruby-identifier">readlines</span>(<span class="ruby-string">&#39;t.txt&#39;</span>, <span class="ruby-value">7</span>)
<span class="ruby-comment"># =&gt; [&quot;First l&quot;, &quot;ine\n&quot;, &quot;Second &quot;, &quot;line\n&quot;, &quot;\n&quot;, &quot;Third l&quot;, &quot;ine\n&quot;, &quot;Fourth &quot;, &quot;line\n&quot;]</span>
</pre>

<p>With arguments <code>sep</code> and  <code>limit</code> given, parses lines as determined by the given line separator and the given line-length limit (see <a href="IO.html#class-IO-label-Line+Separator+and+Line+Limit">Line Separator and Line Limit</a>):</p>

<p>Optional keyword arguments <code>opts</code> specify:</p>
<ul><li>
<p><a href="IO.html#class-IO-label-Open+Options">Open Options</a>.</p>
</li><li>
<p><a href="encodings_rdoc.html#label-Encoding+Options">Encoding options</a>.</p>
</li><li>
<p><a href="IO.html#class-IO-label-Line+IO">Line Options</a>.</p>
</li></ul>

                              <div class="method-source-code" id="readlines-source">
            <pre>static VALUE
rb_io_s_readlines(int argc, VALUE *argv, VALUE io)
{
    VALUE opt;
    struct foreach_arg arg;
    struct getline_arg garg;

    argc = rb_scan_args(argc, argv, &quot;12:&quot;, NULL, NULL, NULL, &amp;opt);
    extract_getline_args(argc-1, argv+1, &amp;garg);
    open_key_args(io, argc, argv, opt, &amp;arg);
    if (NIL_P(arg.io)) return Qnil;
    extract_getline_opts(opt, &amp;garg);
    check_getline_args(&amp;garg.rs, &amp;garg.limit, garg.io = arg.io);
    return rb_ensure(io_s_readlines, (VALUE)&amp;garg, rb_io_close, arg.io);
}</pre>
                              </div>
                            </div>


                          </div>

                  <div id="method-c-select" class="method-detail ">
                      <div class="method-heading">
                        <span class="method-callseq">
                          select(read_ios, write_ios = [], error_ios = [], timeout = nil) &rarr; array or nil
                              </span>
                              <span class="method-click-advice">click to toggle source</span>
                            </div>

                            <div class="method-description">
                              <p>Invokes system call <a href="https://linux.die.net/man/2/select">select(2)</a>, which monitors multiple file descriptors, waiting until one or more of the file descriptors becomes ready for some class of I/O operation.</p>

<p>Not implemented on all platforms.</p>

<p>Each of the arguments <code>read_ios</code>, <code>write_ios</code>, and <code>error_ios</code> is an array of <a href="IO.html"><code>IO</code></a> objects.</p>

<p>Argument <code>timeout</code> is an integer timeout interval in seconds.</p>

<p>The method monitors the IO objects given in all three arrays, waiting for some to be ready; returns a 3-element array whose elements are:</p>
<ul><li>
<p>An array of the objects in <code>read_ios</code> that are ready for reading.</p>
</li><li>
<p>An array of the objects in <code>write_ios</code> that are ready for writing.</p>
</li><li>
<p>An array of the objects in <code>error_ios</code> have pending exceptions.</p>
</li></ul>

<p>If no object becomes ready within the given <code>timeout</code>, <code>nil</code> is returned.</p>

<p>IO.select peeks the buffer of IO objects for testing readability. If the IO buffer is not empty, IO.select immediately notifies readability.  This “peek” only happens for IO objects.  It does not happen for IO-like objects such as OpenSSL::SSL::SSLSocket.</p>

<p>The best way to use IO.select is invoking it after non-blocking methods such as <a href="IO.html#method-i-read_nonblock"><code>read_nonblock</code></a>, <a href="IO.html#method-i-write_nonblock"><code>write_nonblock</code></a>, etc.  The methods raise an exception which is extended by <a href="IO/WaitReadable.html"><code>IO::WaitReadable</code></a> or <a href="IO/WaitWritable.html"><code>IO::WaitWritable</code></a>.  The modules notify how the caller should wait with IO.select.  If <a href="IO/WaitReadable.html"><code>IO::WaitReadable</code></a> is raised, the caller should wait for reading.  If <a href="IO/WaitWritable.html"><code>IO::WaitWritable</code></a> is raised, the caller should wait for writing.</p>

<p>So, blocking read (<a href="IO.html#method-i-readpartial"><code>readpartial</code></a>) can be emulated using <a href="IO.html#method-i-read_nonblock"><code>read_nonblock</code></a> and IO.select as follows:</p>

<pre class="ruby"><span class="ruby-keyword">begin</span>
  <span class="ruby-identifier">result</span> = <span class="ruby-identifier">io_like</span>.<span class="ruby-identifier">read_nonblock</span>(<span class="ruby-identifier">maxlen</span>)
<span class="ruby-keyword">rescue</span> <span class="ruby-constant">IO</span><span class="ruby-operator">::</span><span class="ruby-constant">WaitReadable</span>
  <span class="ruby-constant">IO</span>.<span class="ruby-identifier">select</span>([<span class="ruby-identifier">io_like</span>])
  <span class="ruby-keyword">retry</span>
<span class="ruby-keyword">rescue</span> <span class="ruby-constant">IO</span><span class="ruby-operator">::</span><span class="ruby-constant">WaitWritable</span>
  <span class="ruby-constant">IO</span>.<span class="ruby-identifier">select</span>(<span class="ruby-keyword">nil</span>, [<span class="ruby-identifier">io_like</span>])
  <span class="ruby-keyword">retry</span>
<span class="ruby-keyword">end</span>
</pre>

<p>Especially, the combination of non-blocking methods and IO.select is preferred for <a href="IO.html"><code>IO</code></a> like objects such as OpenSSL::SSL::SSLSocket.  It has <a href="IO.html#method-i-to_io"><code>to_io</code></a> method to return underlying <a href="IO.html"><code>IO</code></a> object.  <a href="IO.html#method-c-select"><code>IO.select</code></a> calls <a href="IO.html#method-i-to_io"><code>to_io</code></a> to obtain the file descriptor to wait.</p>

<p>This means that readability notified by IO.select doesn’t mean readability from OpenSSL::SSL::SSLSocket object.</p>

<p>The most likely situation is that OpenSSL::SSL::SSLSocket buffers some data.  IO.select doesn’t see the buffer.  So IO.select can block when OpenSSL::SSL::SSLSocket#readpartial doesn’t block.</p>

<p>However, several more complicated situations exist.</p>

<p>SSL is a protocol which is sequence of records. The record consists of multiple bytes. So, the remote side of SSL sends a partial record, <a href="IO.html#method-c-select"><code>IO.select</code></a> notifies readability but OpenSSL::SSL::SSLSocket cannot decrypt a byte and OpenSSL::SSL::SSLSocket#readpartial will block.</p>

<p>Also, the remote side can request SSL renegotiation which forces the local SSL engine to write some data. This means OpenSSL::SSL::SSLSocket#readpartial may invoke <a href="IO.html#method-i-write"><code>write</code></a> system call and it can block. In such a situation, OpenSSL::SSL::SSLSocket#read_nonblock raises <a href="IO/WaitWritable.html"><code>IO::WaitWritable</code></a> instead of blocking. So, the caller should wait for ready for writability as above example.</p>

<p>The combination of non-blocking methods and IO.select is also useful for streams such as tty, pipe socket socket when multiple processes read from a stream.</p>

<p>Finally, Linux kernel developers don’t guarantee that readability of select(2) means readability of following read(2) even for a single process; see <a href="https://linux.die.net/man/2/select">select(2)</a></p>

<p>Invoking IO.select before <a href="IO.html#method-i-readpartial"><code>IO#readpartial</code></a> works well as usual. However it is not the best way to use IO.select.</p>

<p>The writability notified by select(2) doesn’t show how many bytes are writable. <a href="IO.html#method-i-write"><code>IO#write</code></a> method blocks until given whole string is written. So, <code>IO#write(two or more bytes)</code> can block after writability is notified by IO.select.  <a href="IO.html#method-i-write_nonblock"><code>IO#write_nonblock</code></a> is required to avoid the blocking.</p>

<p>Blocking write (<a href="IO.html#method-i-write"><code>write</code></a>) can be emulated using <a href="IO.html#method-i-write_nonblock"><code>write_nonblock</code></a> and <a href="IO.html#method-c-select"><code>IO.select</code></a> as follows: <a href="IO/WaitReadable.html"><code>IO::WaitReadable</code></a> should also be rescued for SSL renegotiation in OpenSSL::SSL::SSLSocket.</p>

<pre class="ruby"><span class="ruby-keyword">while</span> <span class="ruby-value">0</span> <span class="ruby-operator">&lt;</span> <span class="ruby-identifier">string</span>.<span class="ruby-identifier">bytesize</span>
  <span class="ruby-keyword">begin</span>
    <span class="ruby-identifier">written</span> = <span class="ruby-identifier">io_like</span>.<span class="ruby-identifier">write_nonblock</span>(<span class="ruby-identifier">string</span>)
  <span class="ruby-keyword">rescue</span> <span class="ruby-constant">IO</span><span class="ruby-operator">::</span><span class="ruby-constant">WaitReadable</span>
    <span class="ruby-constant">IO</span>.<span class="ruby-identifier">select</span>([<span class="ruby-identifier">io_like</span>])
    <span class="ruby-keyword">retry</span>
  <span class="ruby-keyword">rescue</span> <span class="ruby-constant">IO</span><span class="ruby-operator">::</span><span class="ruby-constant">WaitWritable</span>
    <span class="ruby-constant">IO</span>.<span class="ruby-identifier">select</span>(<span class="ruby-keyword">nil</span>, [<span class="ruby-identifier">io_like</span>])
    <span class="ruby-keyword">retry</span>
  <span class="ruby-keyword">end</span>
  <span class="ruby-identifier">string</span> = <span class="ruby-identifier">string</span>.<span class="ruby-identifier">byteslice</span>(<span class="ruby-identifier">written</span><span class="ruby-operator">..</span><span class="ruby-value">-1</span>)
<span class="ruby-keyword">end</span>
</pre>

<p>Example:</p>

<pre class="ruby"><span class="ruby-identifier">rp</span>, <span class="ruby-identifier">wp</span> = <span class="ruby-constant">IO</span>.<span class="ruby-identifier">pipe</span>
<span class="ruby-identifier">mesg</span> = <span class="ruby-string">&quot;ping &quot;</span>
<span class="ruby-value">100</span>.<span class="ruby-identifier">times</span> {
  <span class="ruby-comment"># IO.select follows IO#read.  Not the best way to use IO.select.</span>
  <span class="ruby-identifier">rs</span>, <span class="ruby-identifier">ws</span>, = <span class="ruby-constant">IO</span>.<span class="ruby-identifier">select</span>([<span class="ruby-identifier">rp</span>], [<span class="ruby-identifier">wp</span>])
  <span class="ruby-keyword">if</span> <span class="ruby-identifier">r</span> = <span class="ruby-identifier">rs</span>[<span class="ruby-value">0</span>]
    <span class="ruby-identifier">ret</span> = <span class="ruby-identifier">r</span>.<span class="ruby-identifier">read</span>(<span class="ruby-value">5</span>)
    <span class="ruby-identifier">print</span> <span class="ruby-identifier">ret</span>
    <span class="ruby-keyword">case</span> <span class="ruby-identifier">ret</span>
    <span class="ruby-keyword">when</span> <span class="ruby-regexp">/ping/</span>
      <span class="ruby-identifier">mesg</span> = <span class="ruby-string">&quot;pong\n&quot;</span>
    <span class="ruby-keyword">when</span> <span class="ruby-regexp">/pong/</span>
      <span class="ruby-identifier">mesg</span> = <span class="ruby-string">&quot;ping &quot;</span>
    <span class="ruby-keyword">end</span>
  <span class="ruby-keyword">end</span>
  <span class="ruby-keyword">if</span> <span class="ruby-identifier">w</span> = <span class="ruby-identifier">ws</span>[<span class="ruby-value">0</span>]
    <span class="ruby-identifier">w</span>.<span class="ruby-identifier">write</span>(<span class="ruby-identifier">mesg</span>)
  <span class="ruby-keyword">end</span>
}
</pre>

<p>Output:</p>

<pre class="ruby"><span class="ruby-identifier">ping</span> <span class="ruby-identifier">pong</span>
<span class="ruby-identifier">ping</span> <span class="ruby-identifier">pong</span>
<span class="ruby-identifier">ping</span> <span class="ruby-identifier">pong</span>
(<span class="ruby-identifier">snipped</span>)
<span class="ruby-identifier">ping</span>
</pre>

                              <div class="method-source-code" id="select-source">
            <pre>static VALUE
rb_f_select(int argc, VALUE *argv, VALUE obj)
{
    VALUE scheduler = rb_fiber_scheduler_current();
    if (scheduler != Qnil) {
        // It&#39;s optionally supported.
        VALUE result = rb_fiber_scheduler_io_selectv(scheduler, argc, argv);
        if (!UNDEF_P(result)) return result;
    }

    VALUE timeout;
    struct select_args args;
    struct timeval timerec;
    int i;

    rb_scan_args(argc, argv, &quot;13&quot;, &amp;args.read, &amp;args.write, &amp;args.except, &amp;timeout);
    if (NIL_P(timeout)) {
        args.timeout = 0;
    }
    else {
        timerec = rb_time_interval(timeout);
        args.timeout = &amp;timerec;
    }

    for (i = 0; i &lt; numberof(args.fdsets); ++i)
        rb_fd_init(&amp;args.fdsets[i]);

    return rb_ensure(select_call, (VALUE)&amp;args, select_end, (VALUE)&amp;args);
}</pre>
                              </div>
                            </div>


                          </div>

                  <div id="method-c-sysopen" class="method-detail ">
                      <div class="method-heading">
                        <span class="method-callseq">
                          sysopen(path, mode = &#39;r&#39;, perm = 0666) &rarr; integer
                              </span>
                              <span class="method-click-advice">click to toggle source</span>
                            </div>

                            <div class="method-description">
                              <p>Opens the file at the given path with the given mode and permissions; returns the integer file descriptor.</p>

<p>If the file is to be readable, it must exist; if the file is to be writable and does not exist, it is created with the given permissions:</p>

<pre class="ruby"><span class="ruby-constant">File</span>.<span class="ruby-identifier">write</span>(<span class="ruby-string">&#39;t.tmp&#39;</span>, <span class="ruby-string">&#39;&#39;</span>)  <span class="ruby-comment"># =&gt; 0</span>
<span class="ruby-constant">IO</span>.<span class="ruby-identifier">sysopen</span>(<span class="ruby-string">&#39;t.tmp&#39;</span>)      <span class="ruby-comment"># =&gt; 8</span>
<span class="ruby-constant">IO</span>.<span class="ruby-identifier">sysopen</span>(<span class="ruby-string">&#39;t.tmp&#39;</span>, <span class="ruby-string">&#39;w&#39;</span>) <span class="ruby-comment"># =&gt; 9</span>
</pre>

                              <div class="method-source-code" id="sysopen-source">
            <pre>static VALUE
rb_io_s_sysopen(int argc, VALUE *argv, VALUE _)
{
    VALUE fname, vmode, vperm;
    VALUE intmode;
    int oflags, fd;
    mode_t perm;

    rb_scan_args(argc, argv, &quot;12&quot;, &amp;fname, &amp;vmode, &amp;vperm);
    FilePathValue(fname);

    if (NIL_P(vmode))
        oflags = O_RDONLY;
    else if (!NIL_P(intmode = rb_check_to_integer(vmode, &quot;to_int&quot;)))
        oflags = NUM2INT(intmode);
    else {
        SafeStringValue(vmode);
        oflags = rb_io_modestr_oflags(StringValueCStr(vmode));
    }
    if (NIL_P(vperm)) perm = 0666;
    else              perm = NUM2MODET(vperm);

    RB_GC_GUARD(fname) = rb_str_new4(fname);
    fd = rb_sysopen(fname, oflags, perm);
    return INT2NUM(fd);
}</pre>
                              </div>
                            </div>


                          </div>

                  <div id="method-c-try_convert" class="method-detail ">
                      <div class="method-heading">
                        <span class="method-callseq">
                          try_convert(object) &rarr; new_io or nil
                              </span>
                              <span class="method-click-advice">click to toggle source</span>
                            </div>

                            <div class="method-description">
                              <p>Attempts to convert <code>object</code> into an IO object via method <code>to_io</code>; returns the new IO object if successful, or <code>nil</code> otherwise:</p>

<pre class="ruby"><span class="ruby-constant">IO</span>.<span class="ruby-identifier">try_convert</span>(<span class="ruby-constant">STDOUT</span>)   <span class="ruby-comment"># =&gt; #&lt;IO:&lt;STDOUT&gt;&gt;</span>
<span class="ruby-constant">IO</span>.<span class="ruby-identifier">try_convert</span>(<span class="ruby-constant">ARGF</span>)     <span class="ruby-comment"># =&gt; #&lt;IO:&lt;STDIN&gt;&gt;</span>
<span class="ruby-constant">IO</span>.<span class="ruby-identifier">try_convert</span>(<span class="ruby-string">&#39;STDOUT&#39;</span>) <span class="ruby-comment"># =&gt; nil</span>
</pre>

                              <div class="method-source-code" id="try_convert-source">
            <pre>static VALUE
rb_io_s_try_convert(VALUE dummy, VALUE io)
{
    return rb_io_check_io(io);
}</pre>
                              </div>
                            </div>


                          </div>

                  <div id="method-c-write" class="method-detail ">
                      <div class="method-heading">
                        <span class="method-callseq">
                          write(path, data, offset = 0, **opts)    &rarr; integer
                              </span>
                              <span class="method-click-advice">click to toggle source</span>
                            </div>

                            <div class="method-description">
                              <p>Opens the stream, writes the given <code>data</code> to it, and closes the stream; returns the number of bytes written.</p>

<p>When called from class IO (but not subclasses of IO), this method has potential security vulnerabilities if called with untrusted input; see <a href="command_injection_rdoc.html">Command Injection</a>.</p>

<p>The first argument must be a string that is the path to a file.</p>

<p>With only argument <code>path</code> given, writes the given <code>data</code> to the file at that path:</p>

<pre class="ruby"><span class="ruby-constant">IO</span>.<span class="ruby-identifier">write</span>(<span class="ruby-string">&#39;t.tmp&#39;</span>, <span class="ruby-string">&#39;abc&#39;</span>)    <span class="ruby-comment"># =&gt; 3</span>
<span class="ruby-constant">File</span>.<span class="ruby-identifier">read</span>(<span class="ruby-string">&#39;t.tmp&#39;</span>)          <span class="ruby-comment"># =&gt; &quot;abc&quot;</span>
</pre>

<p>If <code>offset</code> is zero (the default), the file is overwritten:</p>

<pre class="ruby"><span class="ruby-constant">IO</span>.<span class="ruby-identifier">write</span>(<span class="ruby-string">&#39;t.tmp&#39;</span>, <span class="ruby-string">&#39;A&#39;</span>)      <span class="ruby-comment"># =&gt; 1</span>
<span class="ruby-constant">File</span>.<span class="ruby-identifier">read</span>(<span class="ruby-string">&#39;t.tmp&#39;</span>)          <span class="ruby-comment"># =&gt; &quot;A&quot;</span>
</pre>

<p>If <code>offset</code> in within the file content, the file is partly overwritten:</p>

<pre class="ruby"><span class="ruby-constant">IO</span>.<span class="ruby-identifier">write</span>(<span class="ruby-string">&#39;t.tmp&#39;</span>, <span class="ruby-string">&#39;abcdef&#39;</span>) <span class="ruby-comment"># =&gt; 3</span>
<span class="ruby-constant">File</span>.<span class="ruby-identifier">read</span>(<span class="ruby-string">&#39;t.tmp&#39;</span>)          <span class="ruby-comment"># =&gt; &quot;abcdef&quot;</span>
<span class="ruby-comment"># Offset within content.</span>
<span class="ruby-constant">IO</span>.<span class="ruby-identifier">write</span>(<span class="ruby-string">&#39;t.tmp&#39;</span>, <span class="ruby-string">&#39;012&#39;</span>, <span class="ruby-value">2</span>) <span class="ruby-comment"># =&gt; 3</span>
<span class="ruby-constant">File</span>.<span class="ruby-identifier">read</span>(<span class="ruby-string">&#39;t.tmp&#39;</span>)          <span class="ruby-comment"># =&gt; &quot;ab012f&quot;</span>
</pre>

<p>If <code>offset</code> is outside the file content, the file is padded with null characters <code>&quot;\u0000&quot;</code>:</p>

<pre class="ruby"><span class="ruby-constant">IO</span>.<span class="ruby-identifier">write</span>(<span class="ruby-string">&#39;t.tmp&#39;</span>, <span class="ruby-string">&#39;xyz&#39;</span>, <span class="ruby-value">10</span>) <span class="ruby-comment"># =&gt; 3</span>
<span class="ruby-constant">File</span>.<span class="ruby-identifier">read</span>(<span class="ruby-string">&#39;t.tmp&#39;</span>)           <span class="ruby-comment"># =&gt; &quot;ab012f\u0000\u0000\u0000\u0000xyz&quot;</span>
</pre>

<p>Optional keyword arguments <code>opts</code> specify:</p>
<ul><li>
<p><a href="IO.html#class-IO-label-Open+Options">Open Options</a>.</p>
</li><li>
<p><a href="encodings_rdoc.html#label-Encoding+Options">Encoding options</a>.</p>
</li></ul>

                              <div class="method-source-code" id="write-source">
            <pre>static VALUE
rb_io_s_write(int argc, VALUE *argv, VALUE io)
{
    return io_s_write(argc, argv, io, 0);
}</pre>
                              </div>
                            </div>


                          </div>

                          </section>

                <section id="public-instance-5Buntitled-5D-method-details" class="method-section">
                <header>
                <h3>Public Instance Methods</h3>
                </header>

                  <div id="method-i-3C-3C" class="method-detail ">
                      <div class="method-heading">
                        <span class="method-callseq">
                          self &lt;&lt; object &rarr; self
                              </span>
                              <span class="method-click-advice">click to toggle source</span>
                            </div>

                            <div class="method-description">
                              <p>Writes the given <code>object</code> to <code>self</code>, which must be opened for writing (see <a href="File.html#class-File-label-Access+Modes">Access Modes</a>); returns <code>self</code>; if <code>object</code> is not a string, it is converted via method <code>to_s</code>:</p>

<pre class="ruby"><span class="ruby-identifier">$stdout</span> <span class="ruby-operator">&lt;&lt;</span> <span class="ruby-string">&#39;Hello&#39;</span> <span class="ruby-operator">&lt;&lt;</span> <span class="ruby-string">&#39;, &#39;</span> <span class="ruby-operator">&lt;&lt;</span> <span class="ruby-string">&#39;World!&#39;</span> <span class="ruby-operator">&lt;&lt;</span> <span class="ruby-string">&quot;\n&quot;</span>
<span class="ruby-identifier">$stdout</span> <span class="ruby-operator">&lt;&lt;</span> <span class="ruby-string">&#39;foo&#39;</span> <span class="ruby-operator">&lt;&lt;</span> <span class="ruby-value">:bar</span> <span class="ruby-operator">&lt;&lt;</span> <span class="ruby-value">2</span> <span class="ruby-operator">&lt;&lt;</span> <span class="ruby-string">&quot;\n&quot;</span>
</pre>

<p>Output:</p>

<pre>Hello, World!
foobar2</pre>

                              <div class="method-source-code" id="3C-3C-source">
            <pre>VALUE
rb_io_addstr(VALUE io, VALUE str)
{
    rb_io_write(io, str);
    return io;
}</pre>
                              </div>
                            </div>


                          </div>

                  <div id="method-i-advise" class="method-detail ">
                      <div class="method-heading">
                        <span class="method-callseq">
                          advise(advice, offset = 0, len = 0) &rarr; nil
                              </span>
                              <span class="method-click-advice">click to toggle source</span>
                            </div>

                            <div class="method-description">
                              <p>Invokes Posix system call <a href="https://linux.die.net/man/2/posix_fadvise">posix_fadvise(2)</a>, which announces an intention to access data from the current file in a particular manner.</p>

<p>The arguments and results are platform-dependent.</p>

<p>The relevant data is specified by:</p>
<ul><li>
<p><code>offset</code>: The offset of the first byte of data.</p>
</li><li>
<p><code>len</code>: The number of bytes to be accessed; if <code>len</code> is zero, or is larger than the number of bytes remaining, all remaining bytes will be accessed.</p>
</li></ul>

<p>Argument <code>advice</code> is one of the following symbols:</p>
<ul><li>
<p><code>:normal</code>: The application has no advice to give about its access pattern for the specified data. If no advice is given for an open file, this is the default assumption.</p>
</li><li>
<p><code>:sequential</code>: The application expects to access the specified data sequentially (with lower offsets read before higher ones).</p>
</li><li>
<p><code>:random</code>: The specified data will be accessed in random order.</p>
</li><li>
<p><code>:noreuse</code>: The specified data will be accessed only once.</p>
</li><li>
<p><code>:willneed</code>: The specified data will be accessed in the near future.</p>
</li><li>
<p><code>:dontneed</code>: The specified data will not be accessed in the near future.</p>
</li></ul>

<p>Not implemented on all platforms.</p>

                              <div class="method-source-code" id="advise-source">
            <pre>static VALUE
rb_io_advise(int argc, VALUE *argv, VALUE io)
{
    VALUE advice, offset, len;
    rb_off_t off, l;
    rb_io_t *fptr;

    rb_scan_args(argc, argv, &quot;12&quot;, &amp;advice, &amp;offset, &amp;len);
    advice_arg_check(advice);

    io = GetWriteIO(io);
    GetOpenFile(io, fptr);

    off = NIL_P(offset) ? 0 : NUM2OFFT(offset);
    l   = NIL_P(len)    ? 0 : NUM2OFFT(len);

#ifdef HAVE_POSIX_FADVISE
    return do_io_advise(fptr, advice, off, l);
#else
    ((void)off, (void)l);       /* Ignore all hint */
    return Qnil;
#endif
}</pre>
                              </div>
                            </div>


                          </div>

                  <div id="method-i-autoclose-3D" class="method-detail ">
                      <div class="method-heading">
                        <span class="method-callseq">
                          autoclose = bool    &rarr; true or false
                              </span>
                              <span class="method-click-advice">click to toggle source</span>
                            </div>

                            <div class="method-description">
                              <p>Sets auto-close flag.</p>

<pre class="ruby"><span class="ruby-identifier">f</span> = <span class="ruby-constant">File</span>.<span class="ruby-identifier">open</span>(<span class="ruby-constant">File</span><span class="ruby-operator">::</span><span class="ruby-constant">NULL</span>)
<span class="ruby-constant">IO</span>.<span class="ruby-identifier">for_fd</span>(<span class="ruby-identifier">f</span>.<span class="ruby-identifier">fileno</span>).<span class="ruby-identifier">close</span>
<span class="ruby-identifier">f</span>.<span class="ruby-identifier">gets</span> <span class="ruby-comment"># raises Errno::EBADF</span>

<span class="ruby-identifier">f</span> = <span class="ruby-constant">File</span>.<span class="ruby-identifier">open</span>(<span class="ruby-constant">File</span><span class="ruby-operator">::</span><span class="ruby-constant">NULL</span>)
<span class="ruby-identifier">g</span> = <span class="ruby-constant">IO</span>.<span class="ruby-identifier">for_fd</span>(<span class="ruby-identifier">f</span>.<span class="ruby-identifier">fileno</span>)
<span class="ruby-identifier">g</span>.<span class="ruby-identifier">autoclose</span> = <span class="ruby-keyword">false</span>
<span class="ruby-identifier">g</span>.<span class="ruby-identifier">close</span>
<span class="ruby-identifier">f</span>.<span class="ruby-identifier">gets</span> <span class="ruby-comment"># won&#39;t cause Errno::EBADF</span>
</pre>

                              <div class="method-source-code" id="autoclose-3D-source">
            <pre>static VALUE
rb_io_set_autoclose(VALUE io, VALUE autoclose)
{
    rb_io_t *fptr;
    GetOpenFile(io, fptr);
    if (!RTEST(autoclose))
        fptr-&gt;mode |= FMODE_EXTERNAL;
    else
        fptr-&gt;mode &amp;= ~FMODE_EXTERNAL;
    return autoclose;
}</pre>
                              </div>
                            </div>


                          </div>

                  <div id="method-i-autoclose-3F" class="method-detail ">
                      <div class="method-heading">
                        <span class="method-callseq">
                          autoclose?   &rarr; true or false
                              </span>
                              <span class="method-click-advice">click to toggle source</span>
                            </div>

                            <div class="method-description">
                              <p>Returns <code>true</code> if the underlying file descriptor of <em>ios</em> will be closed at its finalization or at calling <a href="IO.html#method-i-close"><code>close</code></a>, otherwise <code>false</code>.</p>

                              <div class="method-source-code" id="autoclose-3F-source">
            <pre>static VALUE
rb_io_autoclose_p(VALUE io)
{
    rb_io_t *fptr = RFILE(io)-&gt;fptr;
    rb_io_check_closed(fptr);
    return RBOOL(!(fptr-&gt;mode &amp; FMODE_EXTERNAL));
}</pre>
                              </div>
                            </div>


                          </div>

                  <div id="method-i-binmode" class="method-detail ">
                      <div class="method-heading">
                        <span class="method-callseq">
                          binmode &rarr; self
                              </span>
                              <span class="method-click-advice">click to toggle source</span>
                            </div>

                            <div class="method-description">
                              <p>Sets the stream’s data mode as binary (see <a href="File.html#class-File-label-Data+Mode">Data Mode</a>).</p>

<p>A stream’s data mode may not be changed from binary to text.</p>

                              <div class="method-source-code" id="binmode-source">
            <pre>static VALUE
rb_io_binmode_m(VALUE io)
{
    VALUE write_io;

    rb_io_ascii8bit_binmode(io);

    write_io = GetWriteIO(io);
    if (write_io != io)
        rb_io_ascii8bit_binmode(write_io);
    return io;
}</pre>
                              </div>
                            </div>


                          </div>

                  <div id="method-i-binmode-3F" class="method-detail ">
                      <div class="method-heading">
                        <span class="method-callseq">
                          binmode? &rarr; true or false
                              </span>
                              <span class="method-click-advice">click to toggle source</span>
                            </div>

                            <div class="method-description">
                              <p>Returns <code>true</code> if the stream is on binary mode, <code>false</code> otherwise. See <a href="File.html#class-File-label-Data+Mode">Data Mode</a>.</p>

                              <div class="method-source-code" id="binmode-3F-source">
            <pre>static VALUE
rb_io_binmode_p(VALUE io)
{
    rb_io_t *fptr;
    GetOpenFile(io, fptr);
    return RBOOL(fptr-&gt;mode &amp; FMODE_BINMODE);
}</pre>
                              </div>
                            </div>


                          </div>

                  <div id="method-i-close" class="method-detail ">
                      <div class="method-heading">
                        <span class="method-callseq">
                          close &rarr; nil
                              </span>
                              <span class="method-click-advice">click to toggle source</span>
                            </div>

                            <div class="method-description">
                              <p>Closes the stream for both reading and writing if open for either or both; returns <code>nil</code>. See <a href="IO.html#class-IO-label-Open+and+Closed+Streams">Open and Closed Streams</a>.</p>

<p>If the stream is open for writing, flushes any buffered writes to the operating system before closing.</p>

<p>If the stream was opened by <a href="IO.html#method-c-popen"><code>IO.popen</code></a>, sets global variable <code>$?</code> (child exit status).</p>

<p>Example:</p>

<pre class="ruby"><span class="ruby-constant">IO</span>.<span class="ruby-identifier">popen</span>(<span class="ruby-string">&#39;ruby&#39;</span>, <span class="ruby-string">&#39;r+&#39;</span>) <span class="ruby-keyword">do</span> <span class="ruby-operator">|</span><span class="ruby-identifier">pipe</span><span class="ruby-operator">|</span>
  <span class="ruby-identifier">puts</span> <span class="ruby-identifier">pipe</span>.<span class="ruby-identifier">closed?</span>
  <span class="ruby-identifier">pipe</span>.<span class="ruby-identifier">close</span>
  <span class="ruby-identifier">puts</span> <span class="ruby-identifier">$?</span>
  <span class="ruby-identifier">puts</span> <span class="ruby-identifier">pipe</span>.<span class="ruby-identifier">closed?</span>
<span class="ruby-keyword">end</span>
</pre>

<p>Output:</p>

<pre>false
pid 13760 exit 0
true</pre>

<p>Related: <a href="IO.html#method-i-close_read"><code>IO#close_read</code></a>, <a href="IO.html#method-i-close_write"><code>IO#close_write</code></a>, <a href="IO.html#method-i-closed-3F"><code>IO#closed?</code></a>.</p>

                              <div class="method-source-code" id="close-source">
            <pre>static VALUE
rb_io_close_m(VALUE io)
{
    rb_io_t *fptr = rb_io_get_fptr(io);
    if (fptr-&gt;fd &lt; 0) {
        return Qnil;
    }
    rb_io_close(io);
    return Qnil;
}</pre>
                              </div>
                            </div>


                          </div>

                  <div id="method-i-close_on_exec-3D" class="method-detail ">
                      <div class="method-heading">
                        <span class="method-callseq">
                          close_on_exec = bool &rarr; true or false
                              </span>
                              <span class="method-click-advice">click to toggle source</span>
                            </div>

                            <div class="method-description">
                              <p>Sets a close-on-exec flag.</p>

<pre class="ruby"><span class="ruby-identifier">f</span> = <span class="ruby-constant">File</span>.<span class="ruby-identifier">open</span>(<span class="ruby-constant">File</span><span class="ruby-operator">::</span><span class="ruby-constant">NULL</span>)
<span class="ruby-identifier">f</span>.<span class="ruby-identifier">close_on_exec</span> = <span class="ruby-keyword">true</span>
<span class="ruby-identifier">system</span>(<span class="ruby-string">&quot;cat&quot;</span>, <span class="ruby-node">&quot;/proc/self/fd/#{f.fileno}&quot;</span>) <span class="ruby-comment"># cat: /proc/self/fd/3: No such file or directory</span>
<span class="ruby-identifier">f</span>.<span class="ruby-identifier">closed?</span>                <span class="ruby-comment">#=&gt; false</span>
</pre>

<p>Ruby sets close-on-exec flags of all file descriptors by default since Ruby 2.0.0. So you don’t need to set by yourself. Also, unsetting a close-on-exec flag can cause file descriptor leak if another thread use fork() and exec() (via system() method for example). If you really needs file descriptor inheritance to child process, use spawn()‘s argument such as fd=&gt;fd.</p>

                              <div class="method-source-code" id="close_on_exec-3D-source">
            <pre>static VALUE
rb_io_set_close_on_exec(VALUE io, VALUE arg)
{
    int flag = RTEST(arg) ? FD_CLOEXEC : 0;
    rb_io_t *fptr;
    VALUE write_io;
    int fd, ret;

    write_io = GetWriteIO(io);
    if (io != write_io) {
        GetOpenFile(write_io, fptr);
        if (fptr &amp;&amp; 0 &lt;= (fd = fptr-&gt;fd)) {
            if ((ret = fcntl(fptr-&gt;fd, F_GETFD)) == -1) rb_sys_fail_path(fptr-&gt;pathv);
            if ((ret &amp; FD_CLOEXEC) != flag) {
                ret = (ret &amp; ~FD_CLOEXEC) | flag;
                ret = fcntl(fd, F_SETFD, ret);
                if (ret != 0) rb_sys_fail_path(fptr-&gt;pathv);
            }
        }

    }

    GetOpenFile(io, fptr);
    if (fptr &amp;&amp; 0 &lt;= (fd = fptr-&gt;fd)) {
        if ((ret = fcntl(fd, F_GETFD)) == -1) rb_sys_fail_path(fptr-&gt;pathv);
        if ((ret &amp; FD_CLOEXEC) != flag) {
            ret = (ret &amp; ~FD_CLOEXEC) | flag;
            ret = fcntl(fd, F_SETFD, ret);
            if (ret != 0) rb_sys_fail_path(fptr-&gt;pathv);
        }
    }
    return Qnil;
}</pre>
                              </div>
                            </div>


                          </div>

                  <div id="method-i-close_on_exec-3F" class="method-detail ">
                      <div class="method-heading">
                        <span class="method-callseq">
                          close_on_exec? &rarr; true or false
                              </span>
                              <span class="method-click-advice">click to toggle source</span>
                            </div>

                            <div class="method-description">
                              <p>Returns <code>true</code> if the stream will be closed on exec, <code>false</code> otherwise:</p>

<pre class="ruby"><span class="ruby-identifier">f</span> = <span class="ruby-constant">File</span>.<span class="ruby-identifier">open</span>(<span class="ruby-string">&#39;t.txt&#39;</span>)
<span class="ruby-identifier">f</span>.<span class="ruby-identifier">close_on_exec?</span> <span class="ruby-comment"># =&gt; true</span>
<span class="ruby-identifier">f</span>.<span class="ruby-identifier">close_on_exec</span> = <span class="ruby-keyword">false</span>
<span class="ruby-identifier">f</span>.<span class="ruby-identifier">close_on_exec?</span> <span class="ruby-comment"># =&gt; false</span>
<span class="ruby-identifier">f</span>.<span class="ruby-identifier">close</span>
</pre>

                              <div class="method-source-code" id="close_on_exec-3F-source">
            <pre>static VALUE
rb_io_close_on_exec_p(VALUE io)
{
    rb_io_t *fptr;
    VALUE write_io;
    int fd, ret;

    write_io = GetWriteIO(io);
    if (io != write_io) {
        GetOpenFile(write_io, fptr);
        if (fptr &amp;&amp; 0 &lt;= (fd = fptr-&gt;fd)) {
            if ((ret = fcntl(fd, F_GETFD)) == -1) rb_sys_fail_path(fptr-&gt;pathv);
            if (!(ret &amp; FD_CLOEXEC)) return Qfalse;
        }
    }

    GetOpenFile(io, fptr);
    if (fptr &amp;&amp; 0 &lt;= (fd = fptr-&gt;fd)) {
        if ((ret = fcntl(fd, F_GETFD)) == -1) rb_sys_fail_path(fptr-&gt;pathv);
        if (!(ret &amp; FD_CLOEXEC)) return Qfalse;
    }
    return Qtrue;
}</pre>
                              </div>
                            </div>


                          </div>

                  <div id="method-i-close_read" class="method-detail ">
                      <div class="method-heading">
                        <span class="method-callseq">
                          close_read &rarr; nil
                              </span>
                              <span class="method-click-advice">click to toggle source</span>
                            </div>

                            <div class="method-description">
                              <p>Closes the stream for reading if open for reading; returns <code>nil</code>. See <a href="IO.html#class-IO-label-Open+and+Closed+Streams">Open and Closed Streams</a>.</p>

<p>If the stream was opened by <a href="IO.html#method-c-popen"><code>IO.popen</code></a> and is also closed for writing, sets global variable <code>$?</code> (child exit status).</p>

<p>Example:</p>

<pre class="ruby"><span class="ruby-constant">IO</span>.<span class="ruby-identifier">popen</span>(<span class="ruby-string">&#39;ruby&#39;</span>, <span class="ruby-string">&#39;r+&#39;</span>) <span class="ruby-keyword">do</span> <span class="ruby-operator">|</span><span class="ruby-identifier">pipe</span><span class="ruby-operator">|</span>
  <span class="ruby-identifier">puts</span> <span class="ruby-identifier">pipe</span>.<span class="ruby-identifier">closed?</span>
  <span class="ruby-identifier">pipe</span>.<span class="ruby-identifier">close_write</span>
  <span class="ruby-identifier">puts</span> <span class="ruby-identifier">pipe</span>.<span class="ruby-identifier">closed?</span>
  <span class="ruby-identifier">pipe</span>.<span class="ruby-identifier">close_read</span>
  <span class="ruby-identifier">puts</span> <span class="ruby-identifier">$?</span>
  <span class="ruby-identifier">puts</span> <span class="ruby-identifier">pipe</span>.<span class="ruby-identifier">closed?</span>
<span class="ruby-keyword">end</span>
</pre>

<p>Output:</p>

<pre>false
false
pid 14748 exit 0
true</pre>

<p>Related: <a href="IO.html#method-i-close"><code>IO#close</code></a>, <a href="IO.html#method-i-close_write"><code>IO#close_write</code></a>, <a href="IO.html#method-i-closed-3F"><code>IO#closed?</code></a>.</p>

                              <div class="method-source-code" id="close_read-source">
            <pre>static VALUE
rb_io_close_read(VALUE io)
{
    rb_io_t *fptr;
    VALUE write_io;

    fptr = rb_io_get_fptr(rb_io_taint_check(io));
    if (fptr-&gt;fd &lt; 0) return Qnil;
    if (is_socket(fptr-&gt;fd, fptr-&gt;pathv)) {
#ifndef SHUT_RD
# define SHUT_RD 0
#endif
        if (shutdown(fptr-&gt;fd, SHUT_RD) &lt; 0)
            rb_sys_fail_path(fptr-&gt;pathv);
        fptr-&gt;mode &amp;= ~FMODE_READABLE;
        if (!(fptr-&gt;mode &amp; FMODE_WRITABLE))
            return rb_io_close(io);
        return Qnil;
    }

    write_io = GetWriteIO(io);
    if (io != write_io) {
        rb_io_t *wfptr;
        wfptr = rb_io_get_fptr(rb_io_taint_check(write_io));
        wfptr-&gt;pid = fptr-&gt;pid;
        fptr-&gt;pid = 0;
        RFILE(io)-&gt;fptr = wfptr;
        /* bind to write_io temporarily to get rid of memory/fd leak */
        fptr-&gt;tied_io_for_writing = 0;
        RFILE(write_io)-&gt;fptr = fptr;
        rb_io_fptr_cleanup(fptr, FALSE);
        /* should not finalize fptr because another thread may be reading it */
        return Qnil;
    }

    if ((fptr-&gt;mode &amp; (FMODE_DUPLEX|FMODE_WRITABLE)) == FMODE_WRITABLE) {
        rb_raise(rb_eIOError, &quot;closing non-duplex IO for reading&quot;);
    }
    return rb_io_close(io);
}</pre>
                              </div>
                            </div>


                          </div>

                  <div id="method-i-close_write" class="method-detail ">
                      <div class="method-heading">
                        <span class="method-callseq">
                          close_write &rarr; nil
                              </span>
                              <span class="method-click-advice">click to toggle source</span>
                            </div>

                            <div class="method-description">
                              <p>Closes the stream for writing if open for writing; returns <code>nil</code>. See <a href="IO.html#class-IO-label-Open+and+Closed+Streams">Open and Closed Streams</a>.</p>

<p>Flushes any buffered writes to the operating system before closing.</p>

<p>If the stream was opened by <a href="IO.html#method-c-popen"><code>IO.popen</code></a> and is also closed for reading, sets global variable <code>$?</code> (child exit status).</p>

<pre class="ruby"><span class="ruby-constant">IO</span>.<span class="ruby-identifier">popen</span>(<span class="ruby-string">&#39;ruby&#39;</span>, <span class="ruby-string">&#39;r+&#39;</span>) <span class="ruby-keyword">do</span> <span class="ruby-operator">|</span><span class="ruby-identifier">pipe</span><span class="ruby-operator">|</span>
  <span class="ruby-identifier">puts</span> <span class="ruby-identifier">pipe</span>.<span class="ruby-identifier">closed?</span>
  <span class="ruby-identifier">pipe</span>.<span class="ruby-identifier">close_read</span>
  <span class="ruby-identifier">puts</span> <span class="ruby-identifier">pipe</span>.<span class="ruby-identifier">closed?</span>
  <span class="ruby-identifier">pipe</span>.<span class="ruby-identifier">close_write</span>
  <span class="ruby-identifier">puts</span> <span class="ruby-identifier">$?</span>
  <span class="ruby-identifier">puts</span> <span class="ruby-identifier">pipe</span>.<span class="ruby-identifier">closed?</span>
<span class="ruby-keyword">end</span>
</pre>

<p>Output:</p>

<pre>false
false
pid 15044 exit 0
true</pre>

<p>Related: <a href="IO.html#method-i-close"><code>IO#close</code></a>, <a href="IO.html#method-i-close_read"><code>IO#close_read</code></a>, <a href="IO.html#method-i-closed-3F"><code>IO#closed?</code></a>.</p>

                              <div class="method-source-code" id="close_write-source">
            <pre>static VALUE
rb_io_close_write(VALUE io)
{
    rb_io_t *fptr;
    VALUE write_io;

    write_io = GetWriteIO(io);
    fptr = rb_io_get_fptr(rb_io_taint_check(write_io));
    if (fptr-&gt;fd &lt; 0) return Qnil;
    if (is_socket(fptr-&gt;fd, fptr-&gt;pathv)) {
#ifndef SHUT_WR
# define SHUT_WR 1
#endif
        if (shutdown(fptr-&gt;fd, SHUT_WR) &lt; 0)
            rb_sys_fail_path(fptr-&gt;pathv);
        fptr-&gt;mode &amp;= ~FMODE_WRITABLE;
        if (!(fptr-&gt;mode &amp; FMODE_READABLE))
            return rb_io_close(write_io);
        return Qnil;
    }

    if ((fptr-&gt;mode &amp; (FMODE_DUPLEX|FMODE_READABLE)) == FMODE_READABLE) {
        rb_raise(rb_eIOError, &quot;closing non-duplex IO for writing&quot;);
    }

    if (io != write_io) {
        fptr = rb_io_get_fptr(rb_io_taint_check(io));
        fptr-&gt;tied_io_for_writing = 0;
    }
    rb_io_close(write_io);
    return Qnil;
}</pre>
                              </div>
                            </div>


                          </div>

                  <div id="method-i-closed-3F" class="method-detail ">
                      <div class="method-heading">
                        <span class="method-callseq">
                          closed? &rarr; true or false
                              </span>
                              <span class="method-click-advice">click to toggle source</span>
                            </div>

                            <div class="method-description">
                              <p>Returns <code>true</code> if the stream is closed for both reading and writing, <code>false</code> otherwise. See <a href="IO.html#class-IO-label-Open+and+Closed+Streams">Open and Closed Streams</a>.</p>

<pre class="ruby"><span class="ruby-constant">IO</span>.<span class="ruby-identifier">popen</span>(<span class="ruby-string">&#39;ruby&#39;</span>, <span class="ruby-string">&#39;r+&#39;</span>) <span class="ruby-keyword">do</span> <span class="ruby-operator">|</span><span class="ruby-identifier">pipe</span><span class="ruby-operator">|</span>
  <span class="ruby-identifier">puts</span> <span class="ruby-identifier">pipe</span>.<span class="ruby-identifier">closed?</span>
  <span class="ruby-identifier">pipe</span>.<span class="ruby-identifier">close_read</span>
  <span class="ruby-identifier">puts</span> <span class="ruby-identifier">pipe</span>.<span class="ruby-identifier">closed?</span>
  <span class="ruby-identifier">pipe</span>.<span class="ruby-identifier">close_write</span>
  <span class="ruby-identifier">puts</span> <span class="ruby-identifier">pipe</span>.<span class="ruby-identifier">closed?</span>
<span class="ruby-keyword">end</span>
</pre>

<p>Output:</p>

<pre class="ruby"><span class="ruby-keyword">false</span>
<span class="ruby-keyword">false</span>
<span class="ruby-keyword">true</span>
</pre>

<p>Related: <a href="IO.html#method-i-close_read"><code>IO#close_read</code></a>, <a href="IO.html#method-i-close_write"><code>IO#close_write</code></a>, <a href="IO.html#method-i-close"><code>IO#close</code></a>.</p>

                              <div class="method-source-code" id="closed-3F-source">
            <pre>VALUE
rb_io_closed_p(VALUE io)
{
    rb_io_t *fptr;
    VALUE write_io;
    rb_io_t *write_fptr;

    write_io = GetWriteIO(io);
    if (io != write_io) {
        write_fptr = RFILE(write_io)-&gt;fptr;
        if (write_fptr &amp;&amp; 0 &lt;= write_fptr-&gt;fd) {
            return Qfalse;
        }
    }

    fptr = rb_io_get_fptr(io);
    return RBOOL(0 &gt; fptr-&gt;fd);
}</pre>
                              </div>
                            </div>


                          </div>

                  <div id="method-i-each" class="method-detail ">
                            <div class="method-heading">
                              <span class="method-name">each</span><span
                                class="method-args">                                   -&gt; enumerator</span>
                              <span class="method-click-advice">click to toggle source</span>
                            </div>

                            <div class="method-description">
                              <p>Calls the block with each remaining line read from the stream; returns <code>self</code>. Does nothing if already at end-of-stream; See <a href="IO.html#class-IO-label-Line+IO">Line IO</a>.</p>

<p>With no arguments given, reads lines as determined by line separator <code>$/</code>:</p>

<pre class="ruby"><span class="ruby-identifier">f</span> = <span class="ruby-constant">File</span>.<span class="ruby-identifier">new</span>(<span class="ruby-string">&#39;t.txt&#39;</span>)
<span class="ruby-identifier">f</span>.<span class="ruby-identifier">each_line</span> {<span class="ruby-operator">|</span><span class="ruby-identifier">line</span><span class="ruby-operator">|</span> <span class="ruby-identifier">p</span> <span class="ruby-identifier">line</span> }
<span class="ruby-identifier">f</span>.<span class="ruby-identifier">each_line</span> {<span class="ruby-operator">|</span><span class="ruby-identifier">line</span><span class="ruby-operator">|</span> <span class="ruby-identifier">fail</span> <span class="ruby-string">&#39;Cannot happen&#39;</span> }
<span class="ruby-identifier">f</span>.<span class="ruby-identifier">close</span>
</pre>

<p>Output:</p>

<pre class="ruby"><span class="ruby-string">&quot;First line\n&quot;</span>
<span class="ruby-string">&quot;Second line\n&quot;</span>
<span class="ruby-string">&quot;\n&quot;</span>
<span class="ruby-string">&quot;Fourth line\n&quot;</span>
<span class="ruby-string">&quot;Fifth line\n&quot;</span>
</pre>

<p>With only string argument <code>sep</code> given, reads lines as determined by line separator <code>sep</code>; see <a href="IO.html#class-IO-label-Line+Separator">Line Separator</a>:</p>

<pre class="ruby"><span class="ruby-identifier">f</span> = <span class="ruby-constant">File</span>.<span class="ruby-identifier">new</span>(<span class="ruby-string">&#39;t.txt&#39;</span>)
<span class="ruby-identifier">f</span>.<span class="ruby-identifier">each_line</span>(<span class="ruby-string">&#39;li&#39;</span>) {<span class="ruby-operator">|</span><span class="ruby-identifier">line</span><span class="ruby-operator">|</span> <span class="ruby-identifier">p</span> <span class="ruby-identifier">line</span> }
<span class="ruby-identifier">f</span>.<span class="ruby-identifier">close</span>
</pre>

<p>Output:</p>

<pre class="ruby"><span class="ruby-string">&quot;First li&quot;</span>
<span class="ruby-string">&quot;ne\nSecond li&quot;</span>
<span class="ruby-string">&quot;ne\n\nFourth li&quot;</span>
<span class="ruby-string">&quot;ne\nFifth li&quot;</span>
<span class="ruby-string">&quot;ne\n&quot;</span>
</pre>

<p>The two special values for <code>sep</code> are honored:</p>

<pre class="ruby"><span class="ruby-identifier">f</span> = <span class="ruby-constant">File</span>.<span class="ruby-identifier">new</span>(<span class="ruby-string">&#39;t.txt&#39;</span>)
<span class="ruby-comment"># Get all into one string.</span>
<span class="ruby-identifier">f</span>.<span class="ruby-identifier">each_line</span>(<span class="ruby-keyword">nil</span>) {<span class="ruby-operator">|</span><span class="ruby-identifier">line</span><span class="ruby-operator">|</span> <span class="ruby-identifier">p</span> <span class="ruby-identifier">line</span> }
<span class="ruby-identifier">f</span>.<span class="ruby-identifier">close</span>
</pre>

<p>Output:</p>

<pre class="ruby"><span class="ruby-string">&quot;First line\nSecond line\n\nFourth line\nFifth line\n&quot;</span>

<span class="ruby-identifier">f</span>.<span class="ruby-identifier">rewind</span>
<span class="ruby-comment"># Get paragraphs (up to two line separators).</span>
<span class="ruby-identifier">f</span>.<span class="ruby-identifier">each_line</span>(<span class="ruby-string">&#39;&#39;</span>) {<span class="ruby-operator">|</span><span class="ruby-identifier">line</span><span class="ruby-operator">|</span> <span class="ruby-identifier">p</span> <span class="ruby-identifier">line</span> }
</pre>

<p>Output:</p>

<pre class="ruby"><span class="ruby-string">&quot;First line\nSecond line\n\n&quot;</span>
<span class="ruby-string">&quot;Fourth line\nFifth line\n&quot;</span>
</pre>

<p>With only integer argument <code>limit</code> given, limits the number of bytes in each line; see <a href="IO.html#class-IO-label-Line+Limit">Line Limit</a>:</p>

<pre class="ruby"><span class="ruby-identifier">f</span> = <span class="ruby-constant">File</span>.<span class="ruby-identifier">new</span>(<span class="ruby-string">&#39;t.txt&#39;</span>)
<span class="ruby-identifier">f</span>.<span class="ruby-identifier">each_line</span>(<span class="ruby-value">8</span>) {<span class="ruby-operator">|</span><span class="ruby-identifier">line</span><span class="ruby-operator">|</span> <span class="ruby-identifier">p</span> <span class="ruby-identifier">line</span> }
<span class="ruby-identifier">f</span>.<span class="ruby-identifier">close</span>
</pre>

<p>Output:</p>

<pre class="ruby"><span class="ruby-string">&quot;First li&quot;</span>
<span class="ruby-string">&quot;ne\n&quot;</span>
<span class="ruby-string">&quot;Second l&quot;</span>
<span class="ruby-string">&quot;ine\n&quot;</span>
<span class="ruby-string">&quot;\n&quot;</span>
<span class="ruby-string">&quot;Fourth l&quot;</span>
<span class="ruby-string">&quot;ine\n&quot;</span>
<span class="ruby-string">&quot;Fifth li&quot;</span>
<span class="ruby-string">&quot;ne\n&quot;</span>
</pre>

<p>With arguments <code>sep</code> and <code>limit</code> given, combines the two behaviors:</p>
<ul><li>
<p>Calls with the next line as determined by line separator <code>sep</code>.</p>
</li><li>
<p>But returns no more bytes than are allowed by the limit.</p>
</li></ul>

<p>Optional keyword argument <code>chomp</code> specifies whether line separators are to be omitted:</p>

<pre class="ruby"><span class="ruby-identifier">f</span> = <span class="ruby-constant">File</span>.<span class="ruby-identifier">new</span>(<span class="ruby-string">&#39;t.txt&#39;</span>)
<span class="ruby-identifier">f</span>.<span class="ruby-identifier">each_line</span>(<span class="ruby-value">chomp:</span> <span class="ruby-keyword">true</span>) {<span class="ruby-operator">|</span><span class="ruby-identifier">line</span><span class="ruby-operator">|</span> <span class="ruby-identifier">p</span> <span class="ruby-identifier">line</span> }
<span class="ruby-identifier">f</span>.<span class="ruby-identifier">close</span>
</pre>

<p>Output:</p>

<pre class="ruby"><span class="ruby-string">&quot;First line&quot;</span>
<span class="ruby-string">&quot;Second line&quot;</span>
<span class="ruby-string">&quot;&quot;</span>
<span class="ruby-string">&quot;Fourth line&quot;</span>
<span class="ruby-string">&quot;Fifth line&quot;</span>
</pre>

<p>Returns an <a href="Enumerator.html"><code>Enumerator</code></a> if no block is given.</p>

                              <div class="method-source-code" id="each-source">
            <pre>static VALUE
rb_io_each_line(int argc, VALUE *argv, VALUE io)
{
    VALUE str;
    struct getline_arg args;

    RETURN_ENUMERATOR(io, argc, argv);
    prepare_getline_args(argc, argv, &amp;args, io);
    if (args.limit == 0)
        rb_raise(rb_eArgError, &quot;invalid limit: 0 for each_line&quot;);
    while (!NIL_P(str = rb_io_getline_1(args.rs, args.limit, args.chomp, io))) {
        rb_yield(str);
    }
    return io;
}</pre>
                              </div>
                            </div>

                            <div class="aliases">
                              Also aliased as: <a href="IO.html#method-i-each_line">each_line</a>
                            </div>

                          </div>

                  <div id="method-i-each_byte" class="method-detail ">
                      <div class="method-heading">
                        <span class="method-callseq">
                          each_byte {|byte| ... } &rarr; self
                              </span>
                              <span class="method-click-advice">click to toggle source</span>
                            </div>
                      <div class="method-heading">
                        <span class="method-callseq">
                          each_byte               &rarr; enumerator
                              </span>
                            </div>

                            <div class="method-description">
                              <p>Calls the given block with each byte (0..255) in the stream; returns <code>self</code>. See <a href="IO.html#class-IO-label-Byte+IO">Byte IO</a>.</p>

<pre class="ruby"><span class="ruby-identifier">f</span> = <span class="ruby-constant">File</span>.<span class="ruby-identifier">new</span>(<span class="ruby-string">&#39;t.rus&#39;</span>)
<span class="ruby-identifier">a</span> = []
<span class="ruby-identifier">f</span>.<span class="ruby-identifier">each_byte</span> {<span class="ruby-operator">|</span><span class="ruby-identifier">b</span><span class="ruby-operator">|</span> <span class="ruby-identifier">a</span> <span class="ruby-operator">&lt;&lt;</span> <span class="ruby-identifier">b</span> }
<span class="ruby-identifier">a</span> <span class="ruby-comment"># =&gt; [209, 130, 208, 181, 209, 129, 209, 130]</span>
<span class="ruby-identifier">f</span>.<span class="ruby-identifier">close</span>
</pre>

<p>Returns an <a href="Enumerator.html"><code>Enumerator</code></a> if no block is given.</p>

<p>Related: <a href="IO.html#method-i-each_char"><code>IO#each_char</code></a>, <a href="IO.html#method-i-each_codepoint"><code>IO#each_codepoint</code></a>.</p>

                              <div class="method-source-code" id="each_byte-source">
            <pre>static VALUE
rb_io_each_byte(VALUE io)
{
    rb_io_t *fptr;

    RETURN_ENUMERATOR(io, 0, 0);
    GetOpenFile(io, fptr);

    do {
        while (fptr-&gt;rbuf.len &gt; 0) {
            char *p = fptr-&gt;rbuf.ptr + fptr-&gt;rbuf.off++;
            fptr-&gt;rbuf.len--;
            rb_yield(INT2FIX(*p &amp; 0xff));
            rb_io_check_byte_readable(fptr);
            errno = 0;
        }
        READ_CHECK(fptr);
    } while (io_fillbuf(fptr) &gt;= 0);
    return io;
}</pre>
                              </div>
                            </div>


                          </div>

                  <div id="method-i-each_char" class="method-detail ">
                      <div class="method-heading">
                        <span class="method-callseq">
                          each_char {|c| ... } &rarr; self
                              </span>
                              <span class="method-click-advice">click to toggle source</span>
                            </div>
                      <div class="method-heading">
                        <span class="method-callseq">
                          each_char            &rarr; enumerator
                              </span>
                            </div>

                            <div class="method-description">
                              <p>Calls the given block with each character in the stream; returns <code>self</code>. See <a href="IO.html#class-IO-label-Character+IO">Character IO</a>.</p>

<pre class="ruby"><span class="ruby-identifier">f</span> = <span class="ruby-constant">File</span>.<span class="ruby-identifier">new</span>(<span class="ruby-string">&#39;t.rus&#39;</span>)
<span class="ruby-identifier">a</span> = []
<span class="ruby-identifier">f</span>.<span class="ruby-identifier">each_char</span> {<span class="ruby-operator">|</span><span class="ruby-identifier">c</span><span class="ruby-operator">|</span> <span class="ruby-identifier">a</span> <span class="ruby-operator">&lt;&lt;</span> <span class="ruby-identifier">c</span>.<span class="ruby-identifier">ord</span> }
<span class="ruby-identifier">a</span> <span class="ruby-comment"># =&gt; [1090, 1077, 1089, 1090]</span>
<span class="ruby-identifier">f</span>.<span class="ruby-identifier">close</span>
</pre>

<p>Returns an <a href="Enumerator.html"><code>Enumerator</code></a> if no block is given.</p>

<p>Related: <a href="IO.html#method-i-each_byte"><code>IO#each_byte</code></a>, <a href="IO.html#method-i-each_codepoint"><code>IO#each_codepoint</code></a>.</p>

                              <div class="method-source-code" id="each_char-source">
            <pre>static VALUE
rb_io_each_char(VALUE io)
{
    rb_io_t *fptr;
    rb_encoding *enc;
    VALUE c;

    RETURN_ENUMERATOR(io, 0, 0);
    GetOpenFile(io, fptr);
    rb_io_check_char_readable(fptr);

    enc = io_input_encoding(fptr);
    READ_CHECK(fptr);
    while (!NIL_P(c = io_getc(fptr, enc))) {
        rb_yield(c);
    }
    return io;
}</pre>
                              </div>
                            </div>


                          </div>

                  <div id="method-i-each_codepoint" class="method-detail ">
                      <div class="method-heading">
                        <span class="method-callseq">
                          each_codepoint {|c| ... } &rarr; self
                              </span>
                              <span class="method-click-advice">click to toggle source</span>
                            </div>
                      <div class="method-heading">
                        <span class="method-callseq">
                          each_codepoint            &rarr; enumerator
                              </span>
                            </div>

                            <div class="method-description">
                              <p>Calls the given block with each codepoint in the stream; returns <code>self</code>:</p>

<pre class="ruby"><span class="ruby-identifier">f</span> = <span class="ruby-constant">File</span>.<span class="ruby-identifier">new</span>(<span class="ruby-string">&#39;t.rus&#39;</span>)
<span class="ruby-identifier">a</span> = []
<span class="ruby-identifier">f</span>.<span class="ruby-identifier">each_codepoint</span> {<span class="ruby-operator">|</span><span class="ruby-identifier">c</span><span class="ruby-operator">|</span> <span class="ruby-identifier">a</span> <span class="ruby-operator">&lt;&lt;</span> <span class="ruby-identifier">c</span> }
<span class="ruby-identifier">a</span> <span class="ruby-comment"># =&gt; [1090, 1077, 1089, 1090]</span>
<span class="ruby-identifier">f</span>.<span class="ruby-identifier">close</span>
</pre>

<p>Returns an <a href="Enumerator.html"><code>Enumerator</code></a> if no block is given.</p>

<p>Related: <a href="IO.html#method-i-each_byte"><code>IO#each_byte</code></a>, <a href="IO.html#method-i-each_char"><code>IO#each_char</code></a>.</p>

                              <div class="method-source-code" id="each_codepoint-source">
            <pre>static VALUE
rb_io_each_codepoint(VALUE io)
{
    rb_io_t *fptr;
    rb_encoding *enc;
    unsigned int c;
    int r, n;

    RETURN_ENUMERATOR(io, 0, 0);
    GetOpenFile(io, fptr);
    rb_io_check_char_readable(fptr);

    READ_CHECK(fptr);
    if (NEED_READCONV(fptr)) {
        SET_BINARY_MODE(fptr);
        r = 1;          /* no invalid char yet */
        for (;;) {
            make_readconv(fptr, 0);
            for (;;) {
                if (fptr-&gt;cbuf.len) {
                    if (fptr-&gt;encs.enc)
                        r = rb_enc_precise_mbclen(fptr-&gt;cbuf.ptr+fptr-&gt;cbuf.off,
                                                  fptr-&gt;cbuf.ptr+fptr-&gt;cbuf.off+fptr-&gt;cbuf.len,
                                                  fptr-&gt;encs.enc);
                    else
                        r = ONIGENC_CONSTRUCT_MBCLEN_CHARFOUND(1);
                    if (!MBCLEN_NEEDMORE_P(r))
                        break;
                    if (fptr-&gt;cbuf.len == fptr-&gt;cbuf.capa) {
                        rb_raise(rb_eIOError, &quot;too long character&quot;);
                    }
                }
                if (more_char(fptr) == MORE_CHAR_FINISHED) {
                    clear_readconv(fptr);
                    if (!MBCLEN_CHARFOUND_P(r)) {
                        enc = fptr-&gt;encs.enc;
                        goto invalid;
                    }
                    return io;
                }
            }
            if (MBCLEN_INVALID_P(r)) {
                enc = fptr-&gt;encs.enc;
                goto invalid;
            }
            n = MBCLEN_CHARFOUND_LEN(r);
            if (fptr-&gt;encs.enc) {
                c = rb_enc_codepoint(fptr-&gt;cbuf.ptr+fptr-&gt;cbuf.off,
                                     fptr-&gt;cbuf.ptr+fptr-&gt;cbuf.off+fptr-&gt;cbuf.len,
                                     fptr-&gt;encs.enc);
            }
            else {
                c = (unsigned char)fptr-&gt;cbuf.ptr[fptr-&gt;cbuf.off];
            }
            fptr-&gt;cbuf.off += n;
            fptr-&gt;cbuf.len -= n;
            rb_yield(UINT2NUM(c));
            rb_io_check_byte_readable(fptr);
        }
    }
    NEED_NEWLINE_DECORATOR_ON_READ_CHECK(fptr);
    enc = io_input_encoding(fptr);
    while (io_fillbuf(fptr) &gt;= 0) {
        r = rb_enc_precise_mbclen(fptr-&gt;rbuf.ptr+fptr-&gt;rbuf.off,
                                  fptr-&gt;rbuf.ptr+fptr-&gt;rbuf.off+fptr-&gt;rbuf.len, enc);
        if (MBCLEN_CHARFOUND_P(r) &amp;&amp;
            (n = MBCLEN_CHARFOUND_LEN(r)) &lt;= fptr-&gt;rbuf.len) {
            c = rb_enc_codepoint(fptr-&gt;rbuf.ptr+fptr-&gt;rbuf.off,
                                 fptr-&gt;rbuf.ptr+fptr-&gt;rbuf.off+fptr-&gt;rbuf.len, enc);
            fptr-&gt;rbuf.off += n;
            fptr-&gt;rbuf.len -= n;
            rb_yield(UINT2NUM(c));
        }
        else if (MBCLEN_INVALID_P(r)) {
            goto invalid;
        }
        else if (MBCLEN_NEEDMORE_P(r)) {
            char cbuf[8], *p = cbuf;
            int more = MBCLEN_NEEDMORE_LEN(r);
            if (more &gt; numberof(cbuf)) goto invalid;
            more += n = fptr-&gt;rbuf.len;
            if (more &gt; numberof(cbuf)) goto invalid;
            while ((n = (int)read_buffered_data(p, more, fptr)) &gt; 0 &amp;&amp;
                   (p += n, (more -= n) &gt; 0)) {
                if (io_fillbuf(fptr) &lt; 0) goto invalid;
                if ((n = fptr-&gt;rbuf.len) &gt; more) n = more;
            }
            r = rb_enc_precise_mbclen(cbuf, p, enc);
            if (!MBCLEN_CHARFOUND_P(r)) goto invalid;
            c = rb_enc_codepoint(cbuf, p, enc);
            rb_yield(UINT2NUM(c));
        }
        else {
            continue;
        }
        rb_io_check_byte_readable(fptr);
    }
    return io;

  invalid:
    rb_raise(rb_eArgError, &quot;invalid byte sequence in %s&quot;, rb_enc_name(enc));
    UNREACHABLE_RETURN(Qundef);
}</pre>
                              </div>
                            </div>


                          </div>

                  <div id="method-i-each_line" class="method-detail method-alias">
                            <div class="method-heading">
                              <span class="method-name">each_line</span><span
                                class="method-args">(*args)</span>
                            </div>

                            <div class="method-description">
                              <p>Calls the block with each remaining line read from the stream; returns <code>self</code>. Does nothing if already at end-of-stream; See <a href="IO.html#class-IO-label-Line+IO">Line IO</a>.</p>

<p>With no arguments given, reads lines as determined by line separator <code>$/</code>:</p>

<pre class="ruby"><span class="ruby-identifier">f</span> = <span class="ruby-constant">File</span>.<span class="ruby-identifier">new</span>(<span class="ruby-string">&#39;t.txt&#39;</span>)
<span class="ruby-identifier">f</span>.<span class="ruby-identifier">each_line</span> {<span class="ruby-operator">|</span><span class="ruby-identifier">line</span><span class="ruby-operator">|</span> <span class="ruby-identifier">p</span> <span class="ruby-identifier">line</span> }
<span class="ruby-identifier">f</span>.<span class="ruby-identifier">each_line</span> {<span class="ruby-operator">|</span><span class="ruby-identifier">line</span><span class="ruby-operator">|</span> <span class="ruby-identifier">fail</span> <span class="ruby-string">&#39;Cannot happen&#39;</span> }
<span class="ruby-identifier">f</span>.<span class="ruby-identifier">close</span>
</pre>

<p>Output:</p>

<pre class="ruby"><span class="ruby-string">&quot;First line\n&quot;</span>
<span class="ruby-string">&quot;Second line\n&quot;</span>
<span class="ruby-string">&quot;\n&quot;</span>
<span class="ruby-string">&quot;Fourth line\n&quot;</span>
<span class="ruby-string">&quot;Fifth line\n&quot;</span>
</pre>

<p>With only string argument <code>sep</code> given, reads lines as determined by line separator <code>sep</code>; see <a href="IO.html#class-IO-label-Line+Separator">Line Separator</a>:</p>

<pre class="ruby"><span class="ruby-identifier">f</span> = <span class="ruby-constant">File</span>.<span class="ruby-identifier">new</span>(<span class="ruby-string">&#39;t.txt&#39;</span>)
<span class="ruby-identifier">f</span>.<span class="ruby-identifier">each_line</span>(<span class="ruby-string">&#39;li&#39;</span>) {<span class="ruby-operator">|</span><span class="ruby-identifier">line</span><span class="ruby-operator">|</span> <span class="ruby-identifier">p</span> <span class="ruby-identifier">line</span> }
<span class="ruby-identifier">f</span>.<span class="ruby-identifier">close</span>
</pre>

<p>Output:</p>

<pre class="ruby"><span class="ruby-string">&quot;First li&quot;</span>
<span class="ruby-string">&quot;ne\nSecond li&quot;</span>
<span class="ruby-string">&quot;ne\n\nFourth li&quot;</span>
<span class="ruby-string">&quot;ne\nFifth li&quot;</span>
<span class="ruby-string">&quot;ne\n&quot;</span>
</pre>

<p>The two special values for <code>sep</code> are honored:</p>

<pre class="ruby"><span class="ruby-identifier">f</span> = <span class="ruby-constant">File</span>.<span class="ruby-identifier">new</span>(<span class="ruby-string">&#39;t.txt&#39;</span>)
<span class="ruby-comment"># Get all into one string.</span>
<span class="ruby-identifier">f</span>.<span class="ruby-identifier">each_line</span>(<span class="ruby-keyword">nil</span>) {<span class="ruby-operator">|</span><span class="ruby-identifier">line</span><span class="ruby-operator">|</span> <span class="ruby-identifier">p</span> <span class="ruby-identifier">line</span> }
<span class="ruby-identifier">f</span>.<span class="ruby-identifier">close</span>
</pre>

<p>Output:</p>

<pre class="ruby"><span class="ruby-string">&quot;First line\nSecond line\n\nFourth line\nFifth line\n&quot;</span>

<span class="ruby-identifier">f</span>.<span class="ruby-identifier">rewind</span>
<span class="ruby-comment"># Get paragraphs (up to two line separators).</span>
<span class="ruby-identifier">f</span>.<span class="ruby-identifier">each_line</span>(<span class="ruby-string">&#39;&#39;</span>) {<span class="ruby-operator">|</span><span class="ruby-identifier">line</span><span class="ruby-operator">|</span> <span class="ruby-identifier">p</span> <span class="ruby-identifier">line</span> }
</pre>

<p>Output:</p>

<pre class="ruby"><span class="ruby-string">&quot;First line\nSecond line\n\n&quot;</span>
<span class="ruby-string">&quot;Fourth line\nFifth line\n&quot;</span>
</pre>

<p>With only integer argument <code>limit</code> given, limits the number of bytes in each line; see <a href="IO.html#class-IO-label-Line+Limit">Line Limit</a>:</p>

<pre class="ruby"><span class="ruby-identifier">f</span> = <span class="ruby-constant">File</span>.<span class="ruby-identifier">new</span>(<span class="ruby-string">&#39;t.txt&#39;</span>)
<span class="ruby-identifier">f</span>.<span class="ruby-identifier">each_line</span>(<span class="ruby-value">8</span>) {<span class="ruby-operator">|</span><span class="ruby-identifier">line</span><span class="ruby-operator">|</span> <span class="ruby-identifier">p</span> <span class="ruby-identifier">line</span> }
<span class="ruby-identifier">f</span>.<span class="ruby-identifier">close</span>
</pre>

<p>Output:</p>

<pre class="ruby"><span class="ruby-string">&quot;First li&quot;</span>
<span class="ruby-string">&quot;ne\n&quot;</span>
<span class="ruby-string">&quot;Second l&quot;</span>
<span class="ruby-string">&quot;ine\n&quot;</span>
<span class="ruby-string">&quot;\n&quot;</span>
<span class="ruby-string">&quot;Fourth l&quot;</span>
<span class="ruby-string">&quot;ine\n&quot;</span>
<span class="ruby-string">&quot;Fifth li&quot;</span>
<span class="ruby-string">&quot;ne\n&quot;</span>
</pre>

<p>With arguments <code>sep</code> and <code>limit</code> given, combines the two behaviors:</p>
<ul><li>
<p>Calls with the next line as determined by line separator <code>sep</code>.</p>
</li><li>
<p>But returns no more bytes than are allowed by the limit.</p>
</li></ul>

<p>Optional keyword argument <code>chomp</code> specifies whether line separators are to be omitted:</p>

<pre class="ruby"><span class="ruby-identifier">f</span> = <span class="ruby-constant">File</span>.<span class="ruby-identifier">new</span>(<span class="ruby-string">&#39;t.txt&#39;</span>)
<span class="ruby-identifier">f</span>.<span class="ruby-identifier">each_line</span>(<span class="ruby-value">chomp:</span> <span class="ruby-keyword">true</span>) {<span class="ruby-operator">|</span><span class="ruby-identifier">line</span><span class="ruby-operator">|</span> <span class="ruby-identifier">p</span> <span class="ruby-identifier">line</span> }
<span class="ruby-identifier">f</span>.<span class="ruby-identifier">close</span>
</pre>

<p>Output:</p>

<pre class="ruby"><span class="ruby-string">&quot;First line&quot;</span>
<span class="ruby-string">&quot;Second line&quot;</span>
<span class="ruby-string">&quot;&quot;</span>
<span class="ruby-string">&quot;Fourth line&quot;</span>
<span class="ruby-string">&quot;Fifth line&quot;</span>
</pre>

<p>Returns an <a href="Enumerator.html"><code>Enumerator</code></a> if no block is given.</p>

                            </div>


                            <div class="aliases">
                              Alias for: <a href="IO.html#method-i-each">each</a>
                            </div>
                          </div>

                  <div id="method-i-eof" class="method-detail ">
                      <div class="method-heading">
                        <span class="method-callseq">
                          eof &rarr; true or false
                              </span>
                              <span class="method-click-advice">click to toggle source</span>
                            </div>

                            <div class="method-description">
                              <p>Returns <code>true</code> if the stream is positioned at its end, <code>false</code> otherwise; see <a href="IO.html#class-IO-label-Position">Position</a>:</p>

<pre class="ruby"><span class="ruby-identifier">f</span> = <span class="ruby-constant">File</span>.<span class="ruby-identifier">open</span>(<span class="ruby-string">&#39;t.txt&#39;</span>)
<span class="ruby-identifier">f</span>.<span class="ruby-identifier">eof</span>           <span class="ruby-comment"># =&gt; false</span>
<span class="ruby-identifier">f</span>.<span class="ruby-identifier">seek</span>(<span class="ruby-value">0</span>, <span class="ruby-value">:END</span>) <span class="ruby-comment"># =&gt; 0</span>
<span class="ruby-identifier">f</span>.<span class="ruby-identifier">eof</span>           <span class="ruby-comment"># =&gt; true</span>
<span class="ruby-identifier">f</span>.<span class="ruby-identifier">close</span>
</pre>

<p>Raises an exception unless the stream is opened for reading; see <a href="File.html#class-File-label-Access+Modes">Mode</a>.</p>

<p>If <code>self</code> is a stream such as pipe or socket, this method blocks until the other end sends some data or closes it:</p>

<pre class="ruby"><span class="ruby-identifier">r</span>, <span class="ruby-identifier">w</span> = <span class="ruby-constant">IO</span>.<span class="ruby-identifier">pipe</span>
<span class="ruby-constant">Thread</span>.<span class="ruby-identifier">new</span> { <span class="ruby-identifier">sleep</span> <span class="ruby-value">1</span>; <span class="ruby-identifier">w</span>.<span class="ruby-identifier">close</span> }
<span class="ruby-identifier">r</span>.<span class="ruby-identifier">eof?</span> <span class="ruby-comment"># =&gt; true # After 1-second wait.</span>

<span class="ruby-identifier">r</span>, <span class="ruby-identifier">w</span> = <span class="ruby-constant">IO</span>.<span class="ruby-identifier">pipe</span>
<span class="ruby-constant">Thread</span>.<span class="ruby-identifier">new</span> { <span class="ruby-identifier">sleep</span> <span class="ruby-value">1</span>; <span class="ruby-identifier">w</span>.<span class="ruby-identifier">puts</span> <span class="ruby-string">&quot;a&quot;</span> }
<span class="ruby-identifier">r</span>.<span class="ruby-identifier">eof?</span>  <span class="ruby-comment"># =&gt; false # After 1-second wait.</span>

<span class="ruby-identifier">r</span>, <span class="ruby-identifier">w</span> = <span class="ruby-constant">IO</span>.<span class="ruby-identifier">pipe</span>
<span class="ruby-identifier">r</span>.<span class="ruby-identifier">eof?</span>  <span class="ruby-comment"># blocks forever</span>
</pre>

<p>Note that this method reads data to the input byte buffer.  So <a href="IO.html#method-i-sysread"><code>IO#sysread</code></a> may not behave as you intend with <a href="IO.html#method-i-eof-3F"><code>IO#eof?</code></a>, unless you call <a href="IO.html#method-i-rewind"><code>IO#rewind</code></a> first (which is not available for some streams).</p>

                              <div class="method-source-code" id="eof-source">
            <pre>VALUE
rb_io_eof(VALUE io)
{
    rb_io_t *fptr;

    GetOpenFile(io, fptr);
    rb_io_check_char_readable(fptr);

    if (READ_CHAR_PENDING(fptr)) return Qfalse;
    if (READ_DATA_PENDING(fptr)) return Qfalse;
    READ_CHECK(fptr);
#if RUBY_CRLF_ENVIRONMENT
    if (!NEED_READCONV(fptr) &amp;&amp; NEED_NEWLINE_DECORATOR_ON_READ(fptr)) {
        return RBOOL(eof(fptr-&gt;fd));;
    }
#endif
    return RBOOL(io_fillbuf(fptr) &lt; 0);
}</pre>
                              </div>
                            </div>

                            <div class="aliases">
                              Also aliased as: <a href="IO.html#method-i-eof-3F">eof?</a>
                            </div>

                          </div>

                  <div id="method-i-eof-3F" class="method-detail method-alias">
                            <div class="method-heading">
                              <span class="method-name">eof?</span><span
                                class="method-args">()</span>
                            </div>

                            <div class="method-description">
                              <p>Returns <code>true</code> if the stream is positioned at its end, <code>false</code> otherwise; see <a href="IO.html#class-IO-label-Position">Position</a>:</p>

<pre class="ruby"><span class="ruby-identifier">f</span> = <span class="ruby-constant">File</span>.<span class="ruby-identifier">open</span>(<span class="ruby-string">&#39;t.txt&#39;</span>)
<span class="ruby-identifier">f</span>.<span class="ruby-identifier">eof</span>           <span class="ruby-comment"># =&gt; false</span>
<span class="ruby-identifier">f</span>.<span class="ruby-identifier">seek</span>(<span class="ruby-value">0</span>, <span class="ruby-value">:END</span>) <span class="ruby-comment"># =&gt; 0</span>
<span class="ruby-identifier">f</span>.<span class="ruby-identifier">eof</span>           <span class="ruby-comment"># =&gt; true</span>
<span class="ruby-identifier">f</span>.<span class="ruby-identifier">close</span>
</pre>

<p>Raises an exception unless the stream is opened for reading; see <a href="File.html#class-File-label-Access+Modes">Mode</a>.</p>

<p>If <code>self</code> is a stream such as pipe or socket, this method blocks until the other end sends some data or closes it:</p>

<pre class="ruby"><span class="ruby-identifier">r</span>, <span class="ruby-identifier">w</span> = <span class="ruby-constant">IO</span>.<span class="ruby-identifier">pipe</span>
<span class="ruby-constant">Thread</span>.<span class="ruby-identifier">new</span> { <span class="ruby-identifier">sleep</span> <span class="ruby-value">1</span>; <span class="ruby-identifier">w</span>.<span class="ruby-identifier">close</span> }
<span class="ruby-identifier">r</span>.<span class="ruby-identifier">eof?</span> <span class="ruby-comment"># =&gt; true # After 1-second wait.</span>

<span class="ruby-identifier">r</span>, <span class="ruby-identifier">w</span> = <span class="ruby-constant">IO</span>.<span class="ruby-identifier">pipe</span>
<span class="ruby-constant">Thread</span>.<span class="ruby-identifier">new</span> { <span class="ruby-identifier">sleep</span> <span class="ruby-value">1</span>; <span class="ruby-identifier">w</span>.<span class="ruby-identifier">puts</span> <span class="ruby-string">&quot;a&quot;</span> }
<span class="ruby-identifier">r</span>.<span class="ruby-identifier">eof?</span>  <span class="ruby-comment"># =&gt; false # After 1-second wait.</span>

<span class="ruby-identifier">r</span>, <span class="ruby-identifier">w</span> = <span class="ruby-constant">IO</span>.<span class="ruby-identifier">pipe</span>
<span class="ruby-identifier">r</span>.<span class="ruby-identifier">eof?</span>  <span class="ruby-comment"># blocks forever</span>
</pre>

<p>Note that this method reads data to the input byte buffer.  So <a href="IO.html#method-i-sysread"><code>IO#sysread</code></a> may not behave as you intend with <a href="IO.html#method-i-eof-3F"><code>IO#eof?</code></a>, unless you call <a href="IO.html#method-i-rewind"><code>IO#rewind</code></a> first (which is not available for some streams).</p>

                            </div>


                            <div class="aliases">
                              Alias for: <a href="IO.html#method-i-eof">eof</a>
                            </div>
                          </div>

                  <div id="method-i-external_encoding" class="method-detail ">
                      <div class="method-heading">
                        <span class="method-callseq">
                          external_encoding &rarr; encoding or nil
                              </span>
                              <span class="method-click-advice">click to toggle source</span>
                            </div>

                            <div class="method-description">
                              <p>Returns the <a href="Encoding.html"><code>Encoding</code></a> object that represents the encoding of the stream, or <code>nil</code> if the stream is in write mode and no encoding is specified.</p>

<p>See <a href="File.html#class-File-label-Encodings">Encodings</a>.</p>

                              <div class="method-source-code" id="external_encoding-source">
            <pre>static VALUE
rb_io_external_encoding(VALUE io)
{
    rb_io_t *fptr = RFILE(rb_io_taint_check(io))-&gt;fptr;

    if (fptr-&gt;encs.enc2) {
        return rb_enc_from_encoding(fptr-&gt;encs.enc2);
    }
    if (fptr-&gt;mode &amp; FMODE_WRITABLE) {
        if (fptr-&gt;encs.enc)
            return rb_enc_from_encoding(fptr-&gt;encs.enc);
        return Qnil;
    }
    return rb_enc_from_encoding(io_read_encoding(fptr));
}</pre>
                              </div>
                            </div>


                          </div>

                  <div id="method-i-fcntl" class="method-detail ">
                      <div class="method-heading">
                        <span class="method-callseq">
                          fcntl(integer_cmd, argument) &rarr; integer
                              </span>
                              <span class="method-click-advice">click to toggle source</span>
                            </div>

                            <div class="method-description">
                              <p>Invokes Posix system call <a href="https://linux.die.net/man/2/fcntl">fcntl(2)</a>, which provides a mechanism for issuing low-level commands to control or query a file-oriented I/O stream. Arguments and results are platform dependent.</p>

<p>If <code>argument</code> is a number, its value is passed directly; if it is a string, it is interpreted as a binary sequence of bytes. (<a href="Array.html#method-i-pack"><code>Array#pack</code></a> might be a useful way to build this string.)</p>

<p>Not implemented on all platforms.</p>

                              <div class="method-source-code" id="fcntl-source">
            <pre>static VALUE
rb_io_fcntl(int argc, VALUE *argv, VALUE io)
{
    VALUE req, arg;

    rb_scan_args(argc, argv, &quot;11&quot;, &amp;req, &amp;arg);
    return rb_fcntl(io, req, arg);
}</pre>
                              </div>
                            </div>


                          </div>

                  <div id="method-i-fdatasync" class="method-detail ">
                      <div class="method-heading">
                        <span class="method-callseq">
                          fdatasync &rarr; 0
                              </span>
                              <span class="method-click-advice">click to toggle source</span>
                            </div>

                            <div class="method-description">
                              <p>Immediately writes to disk all data buffered in the stream, via the operating system’s: <code>fdatasync(2)</code>, if supported, otherwise via <code>fsync(2)</code>, if supported; otherwise raises an exception.</p>

                              <div class="method-source-code" id="fdatasync-source">
            <pre>static VALUE
rb_io_fdatasync(VALUE io)
{
    rb_io_t *fptr;

    io = GetWriteIO(io);
    GetOpenFile(io, fptr);

    if (io_fflush(fptr) &lt; 0)
        rb_sys_fail_on_write(fptr);

    if ((int)rb_thread_io_blocking_region(nogvl_fdatasync, fptr, fptr-&gt;fd) == 0)
        return INT2FIX(0);

    /* fall back */
    return rb_io_fsync(io);
}</pre>
                              </div>
                            </div>


                          </div>

                  <div id="method-i-fileno" class="method-detail ">
                      <div class="method-heading">
                        <span class="method-callseq">
                          fileno &rarr; integer
                              </span>
                              <span class="method-click-advice">click to toggle source</span>
                            </div>

                            <div class="method-description">
                              <p>Returns the integer file descriptor for the stream:</p>

<pre class="ruby"><span class="ruby-identifier">$stdin</span>.<span class="ruby-identifier">fileno</span>             <span class="ruby-comment"># =&gt; 0</span>
<span class="ruby-identifier">$stdout</span>.<span class="ruby-identifier">fileno</span>            <span class="ruby-comment"># =&gt; 1</span>
<span class="ruby-identifier">$stderr</span>.<span class="ruby-identifier">fileno</span>            <span class="ruby-comment"># =&gt; 2</span>
<span class="ruby-constant">File</span>.<span class="ruby-identifier">open</span>(<span class="ruby-string">&#39;t.txt&#39;</span>).<span class="ruby-identifier">fileno</span> <span class="ruby-comment"># =&gt; 10</span>
<span class="ruby-identifier">f</span>.<span class="ruby-identifier">close</span>
</pre>

                              <div class="method-source-code" id="fileno-source">
            <pre>static VALUE
rb_io_fileno(VALUE io)
{
    rb_io_t *fptr = RFILE(io)-&gt;fptr;
    int fd;

    rb_io_check_closed(fptr);
    fd = fptr-&gt;fd;
    return INT2FIX(fd);
}</pre>
                              </div>
                            </div>

                            <div class="aliases">
                              Also aliased as: <a href="IO.html#method-i-to_i">to_i</a>
                            </div>

                          </div>

                  <div id="method-i-flush" class="method-detail ">
                      <div class="method-heading">
                        <span class="method-callseq">
                          flush &rarr; self
                              </span>
                              <span class="method-click-advice">click to toggle source</span>
                            </div>

                            <div class="method-description">
                              <p>Flushes data buffered in <code>self</code> to the operating system (but does not necessarily flush data buffered in the operating system):</p>

<pre class="ruby"><span class="ruby-identifier">$stdout</span>.<span class="ruby-identifier">print</span> <span class="ruby-string">&#39;no newline&#39;</span> <span class="ruby-comment"># Not necessarily flushed.</span>
<span class="ruby-identifier">$stdout</span>.<span class="ruby-identifier">flush</span>              <span class="ruby-comment"># Flushed.</span>
</pre>

                              <div class="method-source-code" id="flush-source">
            <pre>VALUE
rb_io_flush(VALUE io)
{
    return rb_io_flush_raw(io, 1);
}</pre>
                              </div>
                            </div>


                          </div>

                  <div id="method-i-fsync" class="method-detail ">
                      <div class="method-heading">
                        <span class="method-callseq">
                          fsync &rarr; 0
                              </span>
                              <span class="method-click-advice">click to toggle source</span>
                            </div>

                            <div class="method-description">
                              <p>Immediately writes to disk all data buffered in the stream, via the operating system’s <code>fsync(2)</code>.</p>

<p>Note this difference:</p>
<ul><li>
<p><a href="IO.html#method-i-sync-3D"><code>IO#sync=</code></a>: Ensures that data is flushed from the stream’s internal buffers, but does not guarantee that the operating system actually writes the data to disk.</p>
</li><li>
<p><a href="IO.html#method-i-fsync"><code>IO#fsync</code></a>: Ensures both that data is flushed from internal buffers, and that data is written to disk.</p>
</li></ul>

<p>Raises an exception if the operating system does not support <code>fsync(2)</code>.</p>

                              <div class="method-source-code" id="fsync-source">
            <pre>static VALUE
rb_io_fsync(VALUE io)
{
    rb_io_t *fptr;

    io = GetWriteIO(io);
    GetOpenFile(io, fptr);

    if (io_fflush(fptr) &lt; 0)
        rb_sys_fail_on_write(fptr);
    if ((int)rb_thread_io_blocking_region(nogvl_fsync, fptr, fptr-&gt;fd) &lt; 0)
        rb_sys_fail_path(fptr-&gt;pathv);
    return INT2FIX(0);
}</pre>
                              </div>
                            </div>


                          </div>

                  <div id="method-i-getbyte" class="method-detail ">
                      <div class="method-heading">
                        <span class="method-callseq">
                          getbyte &rarr; integer or nil
                              </span>
                              <span class="method-click-advice">click to toggle source</span>
                            </div>

                            <div class="method-description">
                              <p>Reads and returns the next byte (in range 0..255) from the stream; returns <code>nil</code> if already at end-of-stream. See <a href="IO.html#class-IO-label-Byte+IO">Byte IO</a>.</p>

<pre class="ruby"><span class="ruby-identifier">f</span> = <span class="ruby-constant">File</span>.<span class="ruby-identifier">open</span>(<span class="ruby-string">&#39;t.txt&#39;</span>)
<span class="ruby-identifier">f</span>.<span class="ruby-identifier">getbyte</span> <span class="ruby-comment"># =&gt; 70</span>
<span class="ruby-identifier">f</span>.<span class="ruby-identifier">close</span>
<span class="ruby-identifier">f</span> = <span class="ruby-constant">File</span>.<span class="ruby-identifier">open</span>(<span class="ruby-string">&#39;t.rus&#39;</span>)
<span class="ruby-identifier">f</span>.<span class="ruby-identifier">getbyte</span> <span class="ruby-comment"># =&gt; 209</span>
<span class="ruby-identifier">f</span>.<span class="ruby-identifier">close</span>
</pre>

<p>Related: <a href="IO.html#method-i-readbyte"><code>IO#readbyte</code></a> (may raise <a href="EOFError.html"><code>EOFError</code></a>).</p>

                              <div class="method-source-code" id="getbyte-source">
            <pre>VALUE
rb_io_getbyte(VALUE io)
{
    rb_io_t *fptr;
    int c;

    GetOpenFile(io, fptr);
    rb_io_check_byte_readable(fptr);
    READ_CHECK(fptr);
    VALUE r_stdout = rb_ractor_stdout();
    if (fptr-&gt;fd == 0 &amp;&amp; (fptr-&gt;mode &amp; FMODE_TTY) &amp;&amp; RB_TYPE_P(r_stdout, T_FILE)) {
        rb_io_t *ofp;
        GetOpenFile(r_stdout, ofp);
        if (ofp-&gt;mode &amp; FMODE_TTY) {
            rb_io_flush(r_stdout);
        }
    }
    if (io_fillbuf(fptr) &lt; 0) {
        return Qnil;
    }
    fptr-&gt;rbuf.off++;
    fptr-&gt;rbuf.len--;
    c = (unsigned char)fptr-&gt;rbuf.ptr[fptr-&gt;rbuf.off-1];
    return INT2FIX(c &amp; 0xff);
}</pre>
                              </div>
                            </div>


                          </div>

                  <div id="method-i-getc" class="method-detail ">
                      <div class="method-heading">
                        <span class="method-callseq">
                          getc &rarr; character or nil
                              </span>
                              <span class="method-click-advice">click to toggle source</span>
                            </div>

                            <div class="method-description">
                              <p>Reads and returns the next 1-character string from the stream; returns <code>nil</code> if already at end-of-stream. See <a href="IO.html#class-IO-label-Character+IO">Character IO</a>.</p>

<pre class="ruby"><span class="ruby-identifier">f</span> = <span class="ruby-constant">File</span>.<span class="ruby-identifier">open</span>(<span class="ruby-string">&#39;t.txt&#39;</span>)
<span class="ruby-identifier">f</span>.<span class="ruby-identifier">getc</span>     <span class="ruby-comment"># =&gt; &quot;F&quot;</span>
<span class="ruby-identifier">f</span>.<span class="ruby-identifier">close</span>
<span class="ruby-identifier">f</span> = <span class="ruby-constant">File</span>.<span class="ruby-identifier">open</span>(<span class="ruby-string">&#39;t.rus&#39;</span>)
<span class="ruby-identifier">f</span>.<span class="ruby-identifier">getc</span>.<span class="ruby-identifier">ord</span> <span class="ruby-comment"># =&gt; 1090</span>
<span class="ruby-identifier">f</span>.<span class="ruby-identifier">close</span>
</pre>

<p>Related:  <a href="IO.html#method-i-readchar"><code>IO#readchar</code></a> (may raise <a href="EOFError.html"><code>EOFError</code></a>).</p>

                              <div class="method-source-code" id="getc-source">
            <pre>static VALUE
rb_io_getc(VALUE io)
{
    rb_io_t *fptr;
    rb_encoding *enc;

    GetOpenFile(io, fptr);
    rb_io_check_char_readable(fptr);

    enc = io_input_encoding(fptr);
    READ_CHECK(fptr);
    return io_getc(fptr, enc);
}</pre>
                              </div>
                            </div>


                          </div>

                  <div id="method-i-gets" class="method-detail ">
                      <div class="method-heading">
                        <span class="method-callseq">
                          gets(sep = $/, chomp: false)   &rarr; string or nil
                              </span>
                              <span class="method-click-advice">click to toggle source</span>
                            </div>
                      <div class="method-heading">
                        <span class="method-callseq">
                          gets(limit, chomp: false)      &rarr; string or nil
                              </span>
                            </div>
                      <div class="method-heading">
                        <span class="method-callseq">
                          gets(sep, limit, chomp: false) &rarr; string or nil
                              </span>
                            </div>

                            <div class="method-description">
                              <p>Reads and returns a line from the stream; assigns the return value to <code>$_</code>. See <a href="IO.html#class-IO-label-Line+IO">Line IO</a>.</p>

<p>With no arguments given, returns the next line as determined by line separator <code>$/</code>, or <code>nil</code> if none:</p>

<pre class="ruby"><span class="ruby-identifier">f</span> = <span class="ruby-constant">File</span>.<span class="ruby-identifier">open</span>(<span class="ruby-string">&#39;t.txt&#39;</span>)
<span class="ruby-identifier">f</span>.<span class="ruby-identifier">gets</span> <span class="ruby-comment"># =&gt; &quot;First line\n&quot;</span>
<span class="ruby-identifier">$_</span>     <span class="ruby-comment"># =&gt; &quot;First line\n&quot;</span>
<span class="ruby-identifier">f</span>.<span class="ruby-identifier">gets</span> <span class="ruby-comment"># =&gt; &quot;\n&quot;</span>
<span class="ruby-identifier">f</span>.<span class="ruby-identifier">gets</span> <span class="ruby-comment"># =&gt; &quot;Fourth line\n&quot;</span>
<span class="ruby-identifier">f</span>.<span class="ruby-identifier">gets</span> <span class="ruby-comment"># =&gt; &quot;Fifth line\n&quot;</span>
<span class="ruby-identifier">f</span>.<span class="ruby-identifier">gets</span> <span class="ruby-comment"># =&gt; nil</span>
<span class="ruby-identifier">f</span>.<span class="ruby-identifier">close</span>
</pre>

<p>With only string argument <code>sep</code> given, returns the next line as determined by line separator <code>sep</code>, or <code>nil</code> if none; see <a href="IO.html#class-IO-label-Line+Separator">Line Separator</a>:</p>

<pre class="ruby"><span class="ruby-identifier">f</span> = <span class="ruby-constant">File</span>.<span class="ruby-identifier">new</span>(<span class="ruby-string">&#39;t.txt&#39;</span>)
<span class="ruby-identifier">f</span>.<span class="ruby-identifier">gets</span>(<span class="ruby-string">&#39;l&#39;</span>)   <span class="ruby-comment"># =&gt; &quot;First l&quot;</span>
<span class="ruby-identifier">f</span>.<span class="ruby-identifier">gets</span>(<span class="ruby-string">&#39;li&#39;</span>)  <span class="ruby-comment"># =&gt; &quot;ine\nSecond li&quot;</span>
<span class="ruby-identifier">f</span>.<span class="ruby-identifier">gets</span>(<span class="ruby-string">&#39;lin&#39;</span>) <span class="ruby-comment"># =&gt; &quot;ne\n\nFourth lin&quot;</span>
<span class="ruby-identifier">f</span>.<span class="ruby-identifier">gets</span>        <span class="ruby-comment"># =&gt; &quot;e\n&quot;</span>
<span class="ruby-identifier">f</span>.<span class="ruby-identifier">close</span>
</pre>

<p>The two special values for <code>sep</code> are honored:</p>

<pre class="ruby"><span class="ruby-identifier">f</span> = <span class="ruby-constant">File</span>.<span class="ruby-identifier">new</span>(<span class="ruby-string">&#39;t.txt&#39;</span>)
<span class="ruby-comment"># Get all.</span>
<span class="ruby-identifier">f</span>.<span class="ruby-identifier">gets</span>(<span class="ruby-keyword">nil</span>) <span class="ruby-comment"># =&gt; &quot;First line\nSecond line\n\nFourth line\nFifth line\n&quot;</span>
<span class="ruby-identifier">f</span>.<span class="ruby-identifier">rewind</span>
<span class="ruby-comment"># Get paragraph (up to two line separators).</span>
<span class="ruby-identifier">f</span>.<span class="ruby-identifier">gets</span>(<span class="ruby-string">&#39;&#39;</span>)  <span class="ruby-comment"># =&gt; &quot;First line\nSecond line\n\n&quot;</span>
<span class="ruby-identifier">f</span>.<span class="ruby-identifier">close</span>
</pre>

<p>With only integer argument <code>limit</code> given, limits the number of bytes in the line; see <a href="IO.html#class-IO-label-Line+Limit">Line Limit</a>:</p>

<pre class="ruby"><span class="ruby-comment"># No more than one line.</span>
<span class="ruby-constant">File</span>.<span class="ruby-identifier">open</span>(<span class="ruby-string">&#39;t.txt&#39;</span>) {<span class="ruby-operator">|</span><span class="ruby-identifier">f</span><span class="ruby-operator">|</span> <span class="ruby-identifier">f</span>.<span class="ruby-identifier">gets</span>(<span class="ruby-value">10</span>) } <span class="ruby-comment"># =&gt; &quot;First line&quot;</span>
<span class="ruby-constant">File</span>.<span class="ruby-identifier">open</span>(<span class="ruby-string">&#39;t.txt&#39;</span>) {<span class="ruby-operator">|</span><span class="ruby-identifier">f</span><span class="ruby-operator">|</span> <span class="ruby-identifier">f</span>.<span class="ruby-identifier">gets</span>(<span class="ruby-value">11</span>) } <span class="ruby-comment"># =&gt; &quot;First line\n&quot;</span>
<span class="ruby-constant">File</span>.<span class="ruby-identifier">open</span>(<span class="ruby-string">&#39;t.txt&#39;</span>) {<span class="ruby-operator">|</span><span class="ruby-identifier">f</span><span class="ruby-operator">|</span> <span class="ruby-identifier">f</span>.<span class="ruby-identifier">gets</span>(<span class="ruby-value">12</span>) } <span class="ruby-comment"># =&gt; &quot;First line\n&quot;</span>
</pre>

<p>With arguments <code>sep</code> and <code>limit</code> given, combines the two behaviors:</p>
<ul><li>
<p>Returns the next line as determined by line separator <code>sep</code>, or <code>nil</code> if none.</p>
</li><li>
<p>But returns no more bytes than are allowed by the limit.</p>
</li></ul>

<p>Optional keyword argument <code>chomp</code> specifies whether line separators are to be omitted:</p>

<pre class="ruby"><span class="ruby-identifier">f</span> = <span class="ruby-constant">File</span>.<span class="ruby-identifier">open</span>(<span class="ruby-string">&#39;t.txt&#39;</span>)
<span class="ruby-comment"># Chomp the lines.</span>
<span class="ruby-identifier">f</span>.<span class="ruby-identifier">gets</span>(<span class="ruby-value">chomp:</span> <span class="ruby-keyword">true</span>) <span class="ruby-comment"># =&gt; &quot;First line&quot;</span>
<span class="ruby-identifier">f</span>.<span class="ruby-identifier">gets</span>(<span class="ruby-value">chomp:</span> <span class="ruby-keyword">true</span>) <span class="ruby-comment"># =&gt; &quot;Second line&quot;</span>
<span class="ruby-identifier">f</span>.<span class="ruby-identifier">gets</span>(<span class="ruby-value">chomp:</span> <span class="ruby-keyword">true</span>) <span class="ruby-comment"># =&gt; &quot;&quot;</span>
<span class="ruby-identifier">f</span>.<span class="ruby-identifier">gets</span>(<span class="ruby-value">chomp:</span> <span class="ruby-keyword">true</span>) <span class="ruby-comment"># =&gt; &quot;Fourth line&quot;</span>
<span class="ruby-identifier">f</span>.<span class="ruby-identifier">gets</span>(<span class="ruby-value">chomp:</span> <span class="ruby-keyword">true</span>) <span class="ruby-comment"># =&gt; &quot;Fifth line&quot;</span>
<span class="ruby-identifier">f</span>.<span class="ruby-identifier">gets</span>(<span class="ruby-value">chomp:</span> <span class="ruby-keyword">true</span>) <span class="ruby-comment"># =&gt; nil</span>
<span class="ruby-identifier">f</span>.<span class="ruby-identifier">close</span>
</pre>

                              <div class="method-source-code" id="gets-source">
            <pre>static VALUE
rb_io_gets_m(int argc, VALUE *argv, VALUE io)
{
    VALUE str;

    str = rb_io_getline(argc, argv, io);
    rb_lastline_set(str);

    return str;
}</pre>
                              </div>
                            </div>


                          </div>

                  <div id="method-i-inspect" class="method-detail ">
                      <div class="method-heading">
                        <span class="method-callseq">
                          inspect &rarr; string
                              </span>
                              <span class="method-click-advice">click to toggle source</span>
                            </div>

                            <div class="method-description">
                              <p>Returns a string representation of <code>self</code>:</p>

<pre class="ruby"><span class="ruby-identifier">f</span> = <span class="ruby-constant">File</span>.<span class="ruby-identifier">open</span>(<span class="ruby-string">&#39;t.txt&#39;</span>)
<span class="ruby-identifier">f</span>.<span class="ruby-identifier">inspect</span> <span class="ruby-comment"># =&gt; &quot;#&lt;File:t.txt&gt;&quot;</span>
<span class="ruby-identifier">f</span>.<span class="ruby-identifier">close</span>
</pre>

                              <div class="method-source-code" id="inspect-source">
            <pre>static VALUE
rb_io_inspect(VALUE obj)
{
    rb_io_t *fptr;
    VALUE result;
    static const char closed[] = &quot; (closed)&quot;;

    fptr = RFILE(obj)-&gt;fptr;
    if (!fptr) return rb_any_to_s(obj);
    result = rb_str_new_cstr(&quot;#&lt;&quot;);
    rb_str_append(result, rb_class_name(CLASS_OF(obj)));
    rb_str_cat2(result, &quot;:&quot;);
    if (NIL_P(fptr-&gt;pathv)) {
        if (fptr-&gt;fd &lt; 0) {
            rb_str_cat(result, closed+1, strlen(closed)-1);
        }
        else {
            rb_str_catf(result, &quot;fd %d&quot;, fptr-&gt;fd);
        }
    }
    else {
        rb_str_append(result, fptr-&gt;pathv);
        if (fptr-&gt;fd &lt; 0) {
            rb_str_cat(result, closed, strlen(closed));
        }
    }
    return rb_str_cat2(result, &quot;&gt;&quot;);
}</pre>
                              </div>
                            </div>


                          </div>

                  <div id="method-i-internal_encoding" class="method-detail ">
                      <div class="method-heading">
                        <span class="method-callseq">
                          internal_encoding &rarr; encoding or nil
                              </span>
                              <span class="method-click-advice">click to toggle source</span>
                            </div>

                            <div class="method-description">
                              <p>Returns the <a href="Encoding.html"><code>Encoding</code></a> object that represents the encoding of the internal string, if conversion is specified, or <code>nil</code> otherwise.</p>

<p>See <a href="File.html#class-File-label-Encodings">Encodings</a>.</p>

                              <div class="method-source-code" id="internal_encoding-source">
            <pre>static VALUE
rb_io_internal_encoding(VALUE io)
{
    rb_io_t *fptr = RFILE(rb_io_taint_check(io))-&gt;fptr;

    if (!fptr-&gt;encs.enc2) return Qnil;
    return rb_enc_from_encoding(io_read_encoding(fptr));
}</pre>
                              </div>
                            </div>


                          </div>

                  <div id="method-i-ioctl" class="method-detail ">
                      <div class="method-heading">
                        <span class="method-callseq">
                          ioctl(integer_cmd, argument) &rarr; integer
                              </span>
                              <span class="method-click-advice">click to toggle source</span>
                            </div>

                            <div class="method-description">
                              <p>Invokes Posix system call <a href="https://linux.die.net/man/2/ioctl">ioctl(2)</a>, which issues a low-level command to an I/O device.</p>

<p>Issues a low-level command to an I/O device. The arguments and returned value are platform-dependent. The effect of the call is platform-dependent.</p>

<p>If argument <code>argument</code> is an integer, it is passed directly; if it is a string, it is interpreted as a binary sequence of bytes.</p>

<p>Not implemented on all platforms.</p>

                              <div class="method-source-code" id="ioctl-source">
            <pre>static VALUE
rb_io_ioctl(int argc, VALUE *argv, VALUE io)
{
    VALUE req, arg;

    rb_scan_args(argc, argv, &quot;11&quot;, &amp;req, &amp;arg);
    return rb_ioctl(io, req, arg);
}</pre>
                              </div>
                            </div>


                          </div>

                  <div id="method-i-isatty" class="method-detail ">
                      <div class="method-heading">
                        <span class="method-callseq">
                          isatty &rarr; true or false
                              </span>
                              <span class="method-click-advice">click to toggle source</span>
                            </div>

                            <div class="method-description">
                              <p>Returns <code>true</code> if the stream is associated with a terminal device (tty), <code>false</code> otherwise:</p>

<pre class="ruby"><span class="ruby-identifier">f</span> = <span class="ruby-constant">File</span>.<span class="ruby-identifier">new</span>(<span class="ruby-string">&#39;t.txt&#39;</span>).<span class="ruby-identifier">isatty</span>    <span class="ruby-comment">#=&gt; false</span>
<span class="ruby-identifier">f</span>.<span class="ruby-identifier">close</span>
<span class="ruby-identifier">f</span> = <span class="ruby-constant">File</span>.<span class="ruby-identifier">new</span>(<span class="ruby-string">&#39;/dev/tty&#39;</span>).<span class="ruby-identifier">isatty</span> <span class="ruby-comment">#=&gt; true</span>
<span class="ruby-identifier">f</span>.<span class="ruby-identifier">close</span>
</pre>

                              <div class="method-source-code" id="isatty-source">
            <pre>static VALUE
rb_io_isatty(VALUE io)
{
    rb_io_t *fptr;

    GetOpenFile(io, fptr);
    return RBOOL(isatty(fptr-&gt;fd) != 0);
}</pre>
                              </div>
                            </div>

                            <div class="aliases">
                              Also aliased as: <a href="IO.html#method-i-tty-3F">tty?</a>
                            </div>

                          </div>

                  <div id="method-i-lineno" class="method-detail ">
                      <div class="method-heading">
                        <span class="method-callseq">
                          lineno &rarr; integer
                              </span>
                              <span class="method-click-advice">click to toggle source</span>
                            </div>

                            <div class="method-description">
                              <p>Returns the current line number for the stream; see <a href="IO.html#class-IO-label-Line+Number">Line Number</a>.</p>

                              <div class="method-source-code" id="lineno-source">
            <pre>static VALUE
rb_io_lineno(VALUE io)
{
    rb_io_t *fptr;

    GetOpenFile(io, fptr);
    rb_io_check_char_readable(fptr);
    return INT2NUM(fptr-&gt;lineno);
}</pre>
                              </div>
                            </div>


                          </div>

                  <div id="method-i-lineno-3D" class="method-detail ">
                      <div class="method-heading">
                        <span class="method-callseq">
                          lineno = integer &rarr; integer
                              </span>
                              <span class="method-click-advice">click to toggle source</span>
                            </div>

                            <div class="method-description">
                              <p>Sets and returns the line number for the stream; see <a href="IO.html#class-IO-label-Line+Number">Line Number</a>.</p>

                              <div class="method-source-code" id="lineno-3D-source">
            <pre>static VALUE
rb_io_set_lineno(VALUE io, VALUE lineno)
{
    rb_io_t *fptr;

    GetOpenFile(io, fptr);
    rb_io_check_char_readable(fptr);
    fptr-&gt;lineno = NUM2INT(lineno);
    return lineno;
}</pre>
                              </div>
                            </div>


                          </div>

                  <div id="method-i-path" class="method-detail ">
                      <div class="method-heading">
                        <span class="method-callseq">
                          path &rarr; string or nil
                              </span>
                              <span class="method-click-advice">click to toggle source</span>
                            </div>

                            <div class="method-description">
                              <p>Returns the path associated with the <a href="IO.html"><code>IO</code></a>, or <code>nil</code> if there is no path associated with the <a href="IO.html"><code>IO</code></a>. It is not guaranteed that the path exists on the filesystem.</p>

<pre class="ruby"><span class="ruby-identifier">$stdin</span>.<span class="ruby-identifier">path</span> <span class="ruby-comment"># =&gt; &quot;&lt;STDIN&gt;&quot;</span>

<span class="ruby-constant">File</span>.<span class="ruby-identifier">open</span>(<span class="ruby-string">&quot;testfile&quot;</span>) {<span class="ruby-operator">|</span><span class="ruby-identifier">f</span><span class="ruby-operator">|</span> <span class="ruby-identifier">f</span>.<span class="ruby-identifier">path</span>} <span class="ruby-comment"># =&gt; &quot;testfile&quot;</span>
</pre>

                              <div class="method-source-code" id="path-source">
            <pre>VALUE
rb_io_path(VALUE io)
{
    rb_io_t *fptr = RFILE(io)-&gt;fptr;

    if (!fptr)
        return Qnil;

    return rb_obj_dup(fptr-&gt;pathv);
}</pre>
                              </div>
                            </div>

                            <div class="aliases">
                              Also aliased as: <a href="IO.html#method-i-to_path">to_path</a>
                            </div>

                          </div>

                  <div id="method-i-pid" class="method-detail ">
                      <div class="method-heading">
                        <span class="method-callseq">
                          pid &rarr; integer or nil
                              </span>
                              <span class="method-click-advice">click to toggle source</span>
                            </div>

                            <div class="method-description">
                              <p>Returns the process ID of a child process associated with the stream, which will have been set by IO#popen, or <code>nil</code> if the stream was not created by IO#popen:</p>

<pre class="ruby"><span class="ruby-identifier">pipe</span> = <span class="ruby-constant">IO</span>.<span class="ruby-identifier">popen</span>(<span class="ruby-string">&quot;-&quot;</span>)
<span class="ruby-keyword">if</span> <span class="ruby-identifier">pipe</span>
  <span class="ruby-identifier">$stderr</span>.<span class="ruby-identifier">puts</span> <span class="ruby-node">&quot;In parent, child pid is #{pipe.pid}&quot;</span>
<span class="ruby-keyword">else</span>
  <span class="ruby-identifier">$stderr</span>.<span class="ruby-identifier">puts</span> <span class="ruby-node">&quot;In child, pid is #{$$}&quot;</span>
<span class="ruby-keyword">end</span>
</pre>

<p>Output:</p>

<pre>In child, pid is 26209
In parent, child pid is 26209</pre>

                              <div class="method-source-code" id="pid-source">
            <pre>static VALUE
rb_io_pid(VALUE io)
{
    rb_io_t *fptr;

    GetOpenFile(io, fptr);
    if (!fptr-&gt;pid)
        return Qnil;
    return PIDT2NUM(fptr-&gt;pid);
}</pre>
                              </div>
                            </div>


                          </div>

                  <div id="method-i-pos" class="method-detail method-alias">
                            <div class="method-heading">
                              <span class="method-name">pos</span><span
                                class="method-args">()</span>
                            </div>

                            <div class="method-description">
                              <p>Returns the current position (in bytes) in <code>self</code> (see <a href="IO.html#class-IO-label-Position">Position</a>):</p>

<pre class="ruby"><span class="ruby-identifier">f</span> = <span class="ruby-constant">File</span>.<span class="ruby-identifier">open</span>(<span class="ruby-string">&#39;t.txt&#39;</span>)
<span class="ruby-identifier">f</span>.<span class="ruby-identifier">tell</span> <span class="ruby-comment"># =&gt; 0</span>
<span class="ruby-identifier">f</span>.<span class="ruby-identifier">gets</span> <span class="ruby-comment"># =&gt; &quot;First line\n&quot;</span>
<span class="ruby-identifier">f</span>.<span class="ruby-identifier">tell</span> <span class="ruby-comment"># =&gt; 12</span>
<span class="ruby-identifier">f</span>.<span class="ruby-identifier">close</span>
</pre>

<p>Related: <a href="IO.html#method-i-pos-3D"><code>IO#pos=</code></a>, <a href="IO.html#method-i-seek"><code>IO#seek</code></a>.</p>

                            </div>


                            <div class="aliases">
                              Alias for: <a href="IO.html#method-i-tell">tell</a>
                            </div>
                          </div>

                  <div id="method-i-pos-3D" class="method-detail ">
                      <div class="method-heading">
                        <span class="method-callseq">
                          pos = new_position &rarr; new_position
                              </span>
                              <span class="method-click-advice">click to toggle source</span>
                            </div>

                            <div class="method-description">
                              <p>Seeks to the given <code>new_position</code> (in bytes); see <a href="IO.html#class-IO-label-Position">Position</a>:</p>

<pre class="ruby"><span class="ruby-identifier">f</span> = <span class="ruby-constant">File</span>.<span class="ruby-identifier">open</span>(<span class="ruby-string">&#39;t.txt&#39;</span>)
<span class="ruby-identifier">f</span>.<span class="ruby-identifier">tell</span>     <span class="ruby-comment"># =&gt; 0</span>
<span class="ruby-identifier">f</span>.<span class="ruby-identifier">pos</span> = <span class="ruby-value">20</span> <span class="ruby-comment"># =&gt; 20</span>
<span class="ruby-identifier">f</span>.<span class="ruby-identifier">tell</span>     <span class="ruby-comment"># =&gt; 20</span>
<span class="ruby-identifier">f</span>.<span class="ruby-identifier">close</span>
</pre>

<p>Related: <a href="IO.html#method-i-seek"><code>IO#seek</code></a>, <a href="IO.html#method-i-tell"><code>IO#tell</code></a>.</p>

                              <div class="method-source-code" id="pos-3D-source">
            <pre>static VALUE
rb_io_set_pos(VALUE io, VALUE offset)
{
    rb_io_t *fptr;
    rb_off_t pos;

    pos = NUM2OFFT(offset);
    GetOpenFile(io, fptr);
    pos = io_seek(fptr, pos, SEEK_SET);
    if (pos &lt; 0 &amp;&amp; errno) rb_sys_fail_path(fptr-&gt;pathv);

    return OFFT2NUM(pos);
}</pre>
                              </div>
                            </div>


                          </div>

                  <div id="method-i-pread" class="method-detail ">
                      <div class="method-heading">
                        <span class="method-callseq">
                          pread(maxlen, offset)             &rarr; string
                              </span>
                              <span class="method-click-advice">click to toggle source</span>
                            </div>
                      <div class="method-heading">
                        <span class="method-callseq">
                          pread(maxlen, offset, out_string) &rarr; string
                              </span>
                            </div>

                            <div class="method-description">
                              <p>Behaves like <a href="IO.html#method-i-readpartial"><code>IO#readpartial</code></a>, except that it:</p>
<ul><li>
<p>Reads at the given <code>offset</code> (in bytes).</p>
</li><li>
<p>Disregards, and does not modify, the stream’s position (see <a href="IO.html#class-IO-label-Position">Position</a>).</p>
</li><li>
<p>Bypasses any user space buffering in the stream.</p>
</li></ul>

<p>Because this method does not disturb the stream’s state (its position, in particular), <code>pread</code> allows multiple threads and processes to use the same IO object for reading at various offsets.</p>

<pre class="ruby"><span class="ruby-identifier">f</span> = <span class="ruby-constant">File</span>.<span class="ruby-identifier">open</span>(<span class="ruby-string">&#39;t.txt&#39;</span>)
<span class="ruby-identifier">f</span>.<span class="ruby-identifier">read</span> <span class="ruby-comment"># =&gt; &quot;First line\nSecond line\n\nFourth line\nFifth line\n&quot;</span>
<span class="ruby-identifier">f</span>.<span class="ruby-identifier">pos</span>  <span class="ruby-comment"># =&gt; 52</span>
<span class="ruby-comment"># Read 12 bytes at offset 0.</span>
<span class="ruby-identifier">f</span>.<span class="ruby-identifier">pread</span>(<span class="ruby-value">12</span>, <span class="ruby-value">0</span>) <span class="ruby-comment"># =&gt; &quot;First line\n&quot;</span>
<span class="ruby-comment"># Read 9 bytes at offset 8.</span>
<span class="ruby-identifier">f</span>.<span class="ruby-identifier">pread</span>(<span class="ruby-value">9</span>, <span class="ruby-value">8</span>)  <span class="ruby-comment"># =&gt; &quot;ne\nSecon&quot;</span>
<span class="ruby-identifier">f</span>.<span class="ruby-identifier">close</span>
</pre>

<p>Not available on some platforms.</p>

                              <div class="method-source-code" id="pread-source">
            <pre>static VALUE
rb_io_pread(int argc, VALUE *argv, VALUE io)
{
    VALUE len, offset, str;
    rb_io_t *fptr;
    ssize_t n;
    struct prdwr_internal_arg arg = {.io = io};
    int shrinkable;

    rb_scan_args(argc, argv, &quot;21&quot;, &amp;len, &amp;offset, &amp;str);
    arg.count = NUM2SIZET(len);
    arg.offset = NUM2OFFT(offset);

    shrinkable = io_setstrbuf(&amp;str, (long)arg.count);
    if (arg.count == 0) return str;
    arg.buf = RSTRING_PTR(str);

    GetOpenFile(io, fptr);
    rb_io_check_byte_readable(fptr);

    arg.fd = fptr-&gt;fd;
    rb_io_check_closed(fptr);

    rb_str_locktmp(str);
    n = (ssize_t)rb_ensure(pread_internal_call, (VALUE)&amp;arg, rb_str_unlocktmp, str);

    if (n &lt; 0) {
        rb_sys_fail_path(fptr-&gt;pathv);
    }
    io_set_read_length(str, n, shrinkable);
    if (n == 0 &amp;&amp; arg.count &gt; 0) {
        rb_eof_error();
    }

    return str;
}</pre>
                              </div>
                            </div>


                          </div>

                  <div id="method-i-print" class="method-detail ">
                      <div class="method-heading">
                        <span class="method-callseq">
                          print(*objects) &rarr; nil
                              </span>
                              <span class="method-click-advice">click to toggle source</span>
                            </div>

                            <div class="method-description">
                              <p>Writes the given objects to the stream; returns <code>nil</code>. Appends the output record separator <code>$OUTPUT_RECORD_SEPARATOR</code> (<code>$\</code>), if it is not <code>nil</code>. See <a href="IO.html#class-IO-label-Line+IO">Line IO</a>.</p>

<p>With argument <code>objects</code> given, for each object:</p>
<ul><li>
<p>Converts via its method <code>to_s</code> if not a string.</p>
</li><li>
<p>Writes to the stream.</p>
</li><li>
<p>If not the last object, writes the output field separator <code>$OUTPUT_FIELD_SEPARATOR</code> (<code>$,</code>) if it is not <code>nil</code>.</p>
</li></ul>

<p>With default separators:</p>

<pre class="ruby"><span class="ruby-identifier">f</span> = <span class="ruby-constant">File</span>.<span class="ruby-identifier">open</span>(<span class="ruby-string">&#39;t.tmp&#39;</span>, <span class="ruby-string">&#39;w+&#39;</span>)
<span class="ruby-identifier">objects</span> = [<span class="ruby-value">0</span>, <span class="ruby-value">0.0</span>, <span class="ruby-constant">Rational</span>(<span class="ruby-value">0</span>, <span class="ruby-value">1</span>), <span class="ruby-constant">Complex</span>(<span class="ruby-value">0</span>, <span class="ruby-value">0</span>), <span class="ruby-value">:zero</span>, <span class="ruby-string">&#39;zero&#39;</span>]
<span class="ruby-identifier">p</span> <span class="ruby-identifier">$OUTPUT_RECORD_SEPARATOR</span>
<span class="ruby-identifier">p</span> <span class="ruby-identifier">$OUTPUT_FIELD_SEPARATOR</span>
<span class="ruby-identifier">f</span>.<span class="ruby-identifier">print</span>(<span class="ruby-operator">*</span><span class="ruby-identifier">objects</span>)
<span class="ruby-identifier">f</span>.<span class="ruby-identifier">rewind</span>
<span class="ruby-identifier">p</span> <span class="ruby-identifier">f</span>.<span class="ruby-identifier">read</span>
<span class="ruby-identifier">f</span>.<span class="ruby-identifier">close</span>
</pre>

<p>Output:</p>

<pre class="ruby"><span class="ruby-keyword">nil</span>
<span class="ruby-keyword">nil</span>
<span class="ruby-string">&quot;00.00/10+0izerozero&quot;</span>
</pre>

<p>With specified separators:</p>

<pre class="ruby"><span class="ruby-identifier">$\</span> = <span class="ruby-string">&quot;\n&quot;</span>
<span class="ruby-identifier">$,</span> = <span class="ruby-string">&#39;,&#39;</span>
<span class="ruby-identifier">f</span>.<span class="ruby-identifier">rewind</span>
<span class="ruby-identifier">f</span>.<span class="ruby-identifier">print</span>(<span class="ruby-operator">*</span><span class="ruby-identifier">objects</span>)
<span class="ruby-identifier">f</span>.<span class="ruby-identifier">rewind</span>
<span class="ruby-identifier">p</span> <span class="ruby-identifier">f</span>.<span class="ruby-identifier">read</span>
</pre>

<p>Output:</p>

<pre class="ruby"><span class="ruby-string">&quot;0,0.0,0/1,0+0i,zero,zero\n&quot;</span>
</pre>

<p>With no argument given, writes the content of <code>$_</code> (which is usually the most recent user input):</p>

<pre class="ruby"><span class="ruby-identifier">f</span> = <span class="ruby-constant">File</span>.<span class="ruby-identifier">open</span>(<span class="ruby-string">&#39;t.tmp&#39;</span>, <span class="ruby-string">&#39;w+&#39;</span>)
<span class="ruby-identifier">gets</span> <span class="ruby-comment"># Sets $_ to the most recent user input.</span>
<span class="ruby-identifier">f</span>.<span class="ruby-identifier">print</span>
<span class="ruby-identifier">f</span>.<span class="ruby-identifier">close</span>
</pre>

                              <div class="method-source-code" id="print-source">
            <pre>VALUE
rb_io_print(int argc, const VALUE *argv, VALUE out)
{
    int i;
    VALUE line;

    /* if no argument given, print `$_&#39; */
    if (argc == 0) {
        argc = 1;
        line = rb_lastline_get();
        argv = &amp;line;
    }
    if (argc &gt; 1 &amp;&amp; !NIL_P(rb_output_fs)) {
        rb_category_warn(RB_WARN_CATEGORY_DEPRECATED, &quot;$, is set to non-nil value&quot;);
    }
    for (i=0; i&lt;argc; i++) {
        if (!NIL_P(rb_output_fs) &amp;&amp; i&gt;0) {
            rb_io_write(out, rb_output_fs);
        }
        rb_io_write(out, argv[i]);
    }
    if (argc &gt; 0 &amp;&amp; !NIL_P(rb_output_rs)) {
        rb_io_write(out, rb_output_rs);
    }

    return Qnil;
}</pre>
                              </div>
                            </div>


                          </div>

                  <div id="method-i-printf" class="method-detail ">
                      <div class="method-heading">
                        <span class="method-callseq">
                          printf(format_string, *objects) &rarr; nil
                              </span>
                              <span class="method-click-advice">click to toggle source</span>
                            </div>

                            <div class="method-description">
                              <p>Formats and writes <code>objects</code> to the stream.</p>

<p>For details on <code>format_string</code>, see <a href="format_specifications_rdoc.html">Format Specifications</a>.</p>

                              <div class="method-source-code" id="printf-source">
            <pre>VALUE
rb_io_printf(int argc, const VALUE *argv, VALUE out)
{
    rb_io_write(out, rb_f_sprintf(argc, argv));
    return Qnil;
}</pre>
                              </div>
                            </div>


                          </div>

                  <div id="method-i-putc" class="method-detail ">
                      <div class="method-heading">
                        <span class="method-callseq">
                          putc(object) &rarr; object
                              </span>
                              <span class="method-click-advice">click to toggle source</span>
                            </div>

                            <div class="method-description">
                              <p>Writes a character to the stream. See <a href="IO.html#class-IO-label-Character+IO">Character IO</a>.</p>

<p>If <code>object</code> is numeric, converts to integer if necessary, then writes the character whose code is the least significant byte; if <code>object</code> is a string, writes the first character:</p>

<pre class="ruby"><span class="ruby-identifier">$stdout</span>.<span class="ruby-identifier">putc</span> <span class="ruby-string">&quot;A&quot;</span>
<span class="ruby-identifier">$stdout</span>.<span class="ruby-identifier">putc</span> <span class="ruby-value">65</span>
</pre>

<p>Output:</p>

<pre class="ruby"><span class="ruby-constant">AA</span>
</pre>

                              <div class="method-source-code" id="putc-source">
            <pre>static VALUE
rb_io_putc(VALUE io, VALUE ch)
{
    VALUE str;
    if (RB_TYPE_P(ch, T_STRING)) {
        str = rb_str_substr(ch, 0, 1);
    }
    else {
        char c = NUM2CHR(ch);
        str = rb_str_new(&amp;c, 1);
    }
    rb_io_write(io, str);
    return ch;
}</pre>
                              </div>
                            </div>


                          </div>

                  <div id="method-i-puts" class="method-detail ">
                      <div class="method-heading">
                        <span class="method-callseq">
                          puts(*objects) &rarr; nil
                              </span>
                              <span class="method-click-advice">click to toggle source</span>
                            </div>

                            <div class="method-description">
                              <p>Writes the given <code>objects</code> to the stream, which must be open for writing; returns <code>nil</code>.\ Writes a newline after each that does not already end with a newline sequence. If called without arguments, writes a newline. See <a href="IO.html#class-IO-label-Line+IO">Line IO</a>.</p>

<p>Note that each added newline is the character <code>&quot;\n&quot;&lt;//tt&gt;, not the output record separator (&lt;tt&gt;$\</code>).</p>

<p>Treatment for each object:</p>
<ul><li>
<p>String: writes the string.</p>
</li><li>
<p>Neither string nor array: writes <code>object.to_s</code>.</p>
</li><li>
<p>Array: writes each element of the array; arrays may be nested.</p>
</li></ul>

<p>To keep these examples brief, we define this helper method:</p>

<pre class="ruby"><span class="ruby-keyword">def</span> <span class="ruby-identifier ruby-title">show</span>(<span class="ruby-operator">*</span><span class="ruby-identifier">objects</span>)
  <span class="ruby-comment"># Puts objects to file.</span>
  <span class="ruby-identifier">f</span> = <span class="ruby-constant">File</span>.<span class="ruby-identifier">new</span>(<span class="ruby-string">&#39;t.tmp&#39;</span>, <span class="ruby-string">&#39;w+&#39;</span>)
  <span class="ruby-identifier">f</span>.<span class="ruby-identifier">puts</span>(<span class="ruby-identifier">objects</span>)
  <span class="ruby-comment"># Return file content.</span>
  <span class="ruby-identifier">f</span>.<span class="ruby-identifier">rewind</span>
  <span class="ruby-identifier">p</span> <span class="ruby-identifier">f</span>.<span class="ruby-identifier">read</span>
  <span class="ruby-identifier">f</span>.<span class="ruby-identifier">close</span>
<span class="ruby-keyword">end</span>

<span class="ruby-comment"># Strings without newlines.</span>
<span class="ruby-identifier">show</span>(<span class="ruby-string">&#39;foo&#39;</span>, <span class="ruby-string">&#39;bar&#39;</span>, <span class="ruby-string">&#39;baz&#39;</span>)     <span class="ruby-comment"># =&gt; &quot;foo\nbar\nbaz\n&quot;</span>
<span class="ruby-comment"># Strings, some with newlines.</span>
<span class="ruby-identifier">show</span>(<span class="ruby-string">&quot;foo\n&quot;</span>, <span class="ruby-string">&#39;bar&#39;</span>, <span class="ruby-string">&quot;baz\n&quot;</span>) <span class="ruby-comment"># =&gt; &quot;foo\nbar\nbaz\n&quot;</span>

<span class="ruby-comment"># Neither strings nor arrays:</span>
<span class="ruby-identifier">show</span>(<span class="ruby-value">0</span>, <span class="ruby-value">0.0</span>, <span class="ruby-constant">Rational</span>(<span class="ruby-value">0</span>, <span class="ruby-value">1</span>), <span class="ruby-constant">Complex</span>(<span class="ruby-value">9</span>, <span class="ruby-value">0</span>), <span class="ruby-value">:zero</span>)
<span class="ruby-comment"># =&gt; &quot;0\n0.0\n0/1\n9+0i\nzero\n&quot;</span>

<span class="ruby-comment"># Array of strings.</span>
<span class="ruby-identifier">show</span>([<span class="ruby-string">&#39;foo&#39;</span>, <span class="ruby-string">&quot;bar\n&quot;</span>, <span class="ruby-string">&#39;baz&#39;</span>]) <span class="ruby-comment"># =&gt; &quot;foo\nbar\nbaz\n&quot;</span>
<span class="ruby-comment"># Nested arrays.</span>
<span class="ruby-identifier">show</span>([[[<span class="ruby-value">0</span>, <span class="ruby-value">1</span>], <span class="ruby-value">2</span>, <span class="ruby-value">3</span>], <span class="ruby-value">4</span>, <span class="ruby-value">5</span>])  <span class="ruby-comment"># =&gt; &quot;0\n1\n2\n3\n4\n5\n&quot;</span>
</pre>

                              <div class="method-source-code" id="puts-source">
            <pre>VALUE
rb_io_puts(int argc, const VALUE *argv, VALUE out)
{
    VALUE line, args[2];

    /* if no argument given, print newline. */
    if (argc == 0) {
        rb_io_write(out, rb_default_rs);
        return Qnil;
    }
    for (int i = 0; i &lt; argc; i++) {
        // Convert the argument to a string:
        if (RB_TYPE_P(argv[i], T_STRING)) {
            line = argv[i];
        }
        else if (rb_exec_recursive(io_puts_ary, argv[i], out)) {
            continue;
        }
        else {
            line = rb_obj_as_string(argv[i]);
        }

        // Write the line:
        int n = 0;
        if (RSTRING_LEN(line) == 0) {
            args[n++] = rb_default_rs;
        }
        else {
            args[n++] = line;
            if (!rb_str_end_with_asciichar(line, &#39;\n&#39;)) {
                args[n++] = rb_default_rs;
            }
        }

        rb_io_writev(out, n, args);
    }

    return Qnil;
}</pre>
                              </div>
                            </div>


                          </div>

                  <div id="method-i-pwrite" class="method-detail ">
                      <div class="method-heading">
                        <span class="method-callseq">
                          pwrite(object, offset) &rarr; integer
                              </span>
                              <span class="method-click-advice">click to toggle source</span>
                            </div>

                            <div class="method-description">
                              <p>Behaves like <a href="IO.html#method-i-write"><code>IO#write</code></a>, except that it:</p>
<ul><li>
<p>Writes at the given <code>offset</code> (in bytes).</p>
</li><li>
<p>Disregards, and does not modify, the stream’s position (see <a href="IO.html#class-IO-label-Position">Position</a>).</p>
</li><li>
<p>Bypasses any user space buffering in the stream.</p>
</li></ul>

<p>Because this method does not disturb the stream’s state (its position, in particular), <code>pwrite</code> allows multiple threads and processes to use the same IO object for writing at various offsets.</p>

<pre class="ruby"><span class="ruby-identifier">f</span> = <span class="ruby-constant">File</span>.<span class="ruby-identifier">open</span>(<span class="ruby-string">&#39;t.tmp&#39;</span>, <span class="ruby-string">&#39;w+&#39;</span>)
<span class="ruby-comment"># Write 6 bytes at offset 3.</span>
<span class="ruby-identifier">f</span>.<span class="ruby-identifier">pwrite</span>(<span class="ruby-string">&#39;ABCDEF&#39;</span>, <span class="ruby-value">3</span>) <span class="ruby-comment"># =&gt; 6</span>
<span class="ruby-identifier">f</span>.<span class="ruby-identifier">rewind</span>
<span class="ruby-identifier">f</span>.<span class="ruby-identifier">read</span> <span class="ruby-comment"># =&gt; &quot;\u0000\u0000\u0000ABCDEF&quot;</span>
<span class="ruby-identifier">f</span>.<span class="ruby-identifier">close</span>
</pre>

<p>Not available on some platforms.</p>

                              <div class="method-source-code" id="pwrite-source">
            <pre>static VALUE
rb_io_pwrite(VALUE io, VALUE str, VALUE offset)
{
    rb_io_t *fptr;
    ssize_t n;
    struct prdwr_internal_arg arg = {.io = io};
    VALUE tmp;

    if (!RB_TYPE_P(str, T_STRING))
        str = rb_obj_as_string(str);

    arg.offset = NUM2OFFT(offset);

    io = GetWriteIO(io);
    GetOpenFile(io, fptr);
    rb_io_check_writable(fptr);
    arg.fd = fptr-&gt;fd;

    tmp = rb_str_tmp_frozen_acquire(str);
    arg.buf = RSTRING_PTR(tmp);
    arg.count = (size_t)RSTRING_LEN(tmp);

    n = (ssize_t)rb_thread_io_blocking_region(internal_pwrite_func, &amp;arg, fptr-&gt;fd);
    if (n &lt; 0) rb_sys_fail_path(fptr-&gt;pathv);
    rb_str_tmp_frozen_release(str, tmp);

    return SSIZET2NUM(n);
}</pre>
                              </div>
                            </div>


                          </div>

                  <div id="method-i-read" class="method-detail ">
                      <div class="method-heading">
                        <span class="method-callseq">
                          read(maxlen = nil, out_string = nil) &rarr; new_string, out_string, or nil
                              </span>
                              <span class="method-click-advice">click to toggle source</span>
                            </div>

                            <div class="method-description">
                              <p>Reads bytes from the stream; the stream must be opened for reading (see <a href="File.html#class-File-label-Access+Modes">Access Modes</a>):</p>
<ul><li>
<p>If <code>maxlen</code> is <code>nil</code>, reads all bytes using the stream’s data mode.</p>
</li><li>
<p>Otherwise reads up to <code>maxlen</code> bytes in binary mode.</p>
</li></ul>

<p>Returns a string (either a new string or the given <code>out_string</code>) containing the bytes read. The encoding of the string depends on both <code>maxLen</code> and <code>out_string</code>:</p>
<ul><li>
<p><code>maxlen</code> is <code>nil</code>: uses internal encoding of <code>self</code> (regardless of whether <code>out_string</code> was given).</p>
</li><li>
<p><code>maxlen</code> not <code>nil</code>:</p>
<ul><li>
<p><code>out_string</code> given: encoding of <code>out_string</code> not modified.</p>
</li><li>
<p><code>out_string</code> not given: ASCII-8BIT is used.</p>
</li></ul>
</li></ul>

<p><strong>Without Argument <code>out_string</code></strong></p>

<p>When argument <code>out_string</code> is omitted, the returned value is a new string:</p>

<pre class="ruby"><span class="ruby-identifier">f</span> = <span class="ruby-constant">File</span>.<span class="ruby-identifier">new</span>(<span class="ruby-string">&#39;t.txt&#39;</span>)
<span class="ruby-identifier">f</span>.<span class="ruby-identifier">read</span>
<span class="ruby-comment"># =&gt; &quot;First line\nSecond line\n\nFourth line\nFifth line\n&quot;</span>
<span class="ruby-identifier">f</span>.<span class="ruby-identifier">rewind</span>
<span class="ruby-identifier">f</span>.<span class="ruby-identifier">read</span>(<span class="ruby-value">30</span>) <span class="ruby-comment"># =&gt; &quot;First line\r\nSecond line\r\n\r\nFou&quot;</span>
<span class="ruby-identifier">f</span>.<span class="ruby-identifier">read</span>(<span class="ruby-value">30</span>) <span class="ruby-comment"># =&gt; &quot;rth line\r\nFifth line\r\n&quot;</span>
<span class="ruby-identifier">f</span>.<span class="ruby-identifier">read</span>(<span class="ruby-value">30</span>) <span class="ruby-comment"># =&gt; nil</span>
<span class="ruby-identifier">f</span>.<span class="ruby-identifier">close</span>
</pre>

<p>If <code>maxlen</code> is zero, returns an empty string.</p>

<p><strong> With Argument <code>out_string</code></strong></p>

<p>When argument <code>out_string</code> is given, the returned value is <code>out_string</code>, whose content is replaced:</p>

<pre class="ruby"><span class="ruby-identifier">f</span> = <span class="ruby-constant">File</span>.<span class="ruby-identifier">new</span>(<span class="ruby-string">&#39;t.txt&#39;</span>)
<span class="ruby-identifier">s</span> = <span class="ruby-string">&#39;foo&#39;</span>      <span class="ruby-comment"># =&gt; &quot;foo&quot;</span>
<span class="ruby-identifier">f</span>.<span class="ruby-identifier">read</span>(<span class="ruby-keyword">nil</span>, <span class="ruby-identifier">s</span>) <span class="ruby-comment"># =&gt; &quot;First line\nSecond line\n\nFourth line\nFifth line\n&quot;</span>
<span class="ruby-identifier">s</span>              <span class="ruby-comment"># =&gt; &quot;First line\nSecond line\n\nFourth line\nFifth line\n&quot;</span>
<span class="ruby-identifier">f</span>.<span class="ruby-identifier">rewind</span>
<span class="ruby-identifier">s</span> = <span class="ruby-string">&#39;bar&#39;</span>
<span class="ruby-identifier">f</span>.<span class="ruby-identifier">read</span>(<span class="ruby-value">30</span>, <span class="ruby-identifier">s</span>)  <span class="ruby-comment"># =&gt; &quot;First line\r\nSecond line\r\n\r\nFou&quot;</span>
<span class="ruby-identifier">s</span>              <span class="ruby-comment"># =&gt; &quot;First line\r\nSecond line\r\n\r\nFou&quot;</span>
<span class="ruby-identifier">s</span> = <span class="ruby-string">&#39;baz&#39;</span>
<span class="ruby-identifier">f</span>.<span class="ruby-identifier">read</span>(<span class="ruby-value">30</span>, <span class="ruby-identifier">s</span>)  <span class="ruby-comment"># =&gt; &quot;rth line\r\nFifth line\r\n&quot;</span>
<span class="ruby-identifier">s</span>              <span class="ruby-comment"># =&gt; &quot;rth line\r\nFifth line\r\n&quot;</span>
<span class="ruby-identifier">s</span> = <span class="ruby-string">&#39;bat&#39;</span>
<span class="ruby-identifier">f</span>.<span class="ruby-identifier">read</span>(<span class="ruby-value">30</span>, <span class="ruby-identifier">s</span>)  <span class="ruby-comment"># =&gt; nil</span>
<span class="ruby-identifier">s</span>              <span class="ruby-comment"># =&gt; &quot;&quot;</span>
<span class="ruby-identifier">f</span>.<span class="ruby-identifier">close</span>
</pre>

<p>Note that this method behaves like the fread() function in C. This means it retries to invoke read(2) system calls to read data with the specified maxlen (or until EOF).</p>

<p>This behavior is preserved even if the stream is in non-blocking mode. (This method is non-blocking-flag insensitive as other methods.)</p>

<p>If you need the behavior like a single read(2) system call, consider <a href="IO.html#method-i-readpartial"><code>readpartial</code></a>, <a href="IO.html#method-i-read_nonblock"><code>read_nonblock</code></a>, and <a href="IO.html#method-i-sysread"><code>sysread</code></a>.</p>

<p>Related: <a href="IO.html#method-i-write"><code>IO#write</code></a>.</p>

                              <div class="method-source-code" id="read-source">
            <pre>static VALUE
io_read(int argc, VALUE *argv, VALUE io)
{
    rb_io_t *fptr;
    long n, len;
    VALUE length, str;
    int shrinkable;
#if RUBY_CRLF_ENVIRONMENT
    int previous_mode;
#endif

    rb_scan_args(argc, argv, &quot;02&quot;, &amp;length, &amp;str);

    if (NIL_P(length)) {
        GetOpenFile(io, fptr);
        rb_io_check_char_readable(fptr);
        return read_all(fptr, remain_size(fptr), str);
    }
    len = NUM2LONG(length);
    if (len &lt; 0) {
        rb_raise(rb_eArgError, &quot;negative length %ld given&quot;, len);
    }

    shrinkable = io_setstrbuf(&amp;str,len);

    GetOpenFile(io, fptr);
    rb_io_check_byte_readable(fptr);
    if (len == 0) {
        io_set_read_length(str, 0, shrinkable);
        return str;
    }

    READ_CHECK(fptr);
#if RUBY_CRLF_ENVIRONMENT
    previous_mode = set_binary_mode_with_seek_cur(fptr);
#endif
    n = io_fread(str, 0, len, fptr);
    io_set_read_length(str, n, shrinkable);
#if RUBY_CRLF_ENVIRONMENT
    if (previous_mode == O_TEXT) {
        setmode(fptr-&gt;fd, O_TEXT);
    }
#endif
    if (n == 0) return Qnil;

    return str;
}</pre>
                              </div>
                            </div>


                          </div>

                  <div id="method-i-read_nonblock" class="method-detail ">
                      <div class="method-heading">
                        <span class="method-callseq">
                          read_nonblock(maxlen [, options])              &rarr; string
                              </span>
                              <span class="method-click-advice">click to toggle source</span>
                            </div>
                      <div class="method-heading">
                        <span class="method-callseq">
                          read_nonblock(maxlen, outbuf [, options])      &rarr; outbuf
                              </span>
                            </div>

                            <div class="method-description">
                              <p>Reads at most <em>maxlen</em> bytes from <em>ios</em> using the read(2) system call after O_NONBLOCK is set for the underlying file descriptor.</p>

<p>If the optional <em>outbuf</em> argument is present, it must reference a <a href="String.html"><code>String</code></a>, which will receive the data. The <em>outbuf</em> will contain only the received data after the method call even if it is not empty at the beginning.</p>

<p><a href="IO.html#method-i-read_nonblock"><code>read_nonblock</code></a> just calls the read(2) system call. It causes all errors the read(2) system call causes: Errno::EWOULDBLOCK, Errno::EINTR, etc. The caller should care such errors.</p>

<p>If the exception is Errno::EWOULDBLOCK or Errno::EAGAIN, it is extended by <a href="IO/WaitReadable.html"><code>IO::WaitReadable</code></a>. So <a href="IO/WaitReadable.html"><code>IO::WaitReadable</code></a> can be used to rescue the exceptions for retrying read_nonblock.</p>

<p><a href="IO.html#method-i-read_nonblock"><code>read_nonblock</code></a> causes <a href="EOFError.html"><code>EOFError</code></a> on EOF.</p>

<p>On some platforms, such as Windows, non-blocking mode is not supported on <a href="IO.html"><code>IO</code></a> objects other than sockets. In such cases, Errno::EBADF will be raised.</p>

<p>If the read byte buffer is not empty, <a href="IO.html#method-i-read_nonblock"><code>read_nonblock</code></a> reads from the buffer like readpartial. In this case, the read(2) system call is not called.</p>

<p>When <a href="IO.html#method-i-read_nonblock"><code>read_nonblock</code></a> raises an exception kind of <a href="IO/WaitReadable.html"><code>IO::WaitReadable</code></a>, <a href="IO.html#method-i-read_nonblock"><code>read_nonblock</code></a> should not be called until io is readable for avoiding busy loop. This can be done as follows.</p>

<pre class="ruby"><span class="ruby-comment"># emulates blocking read (readpartial).</span>
<span class="ruby-keyword">begin</span>
  <span class="ruby-identifier">result</span> = <span class="ruby-identifier">io</span>.<span class="ruby-identifier">read_nonblock</span>(<span class="ruby-identifier">maxlen</span>)
<span class="ruby-keyword">rescue</span> <span class="ruby-constant">IO</span><span class="ruby-operator">::</span><span class="ruby-constant">WaitReadable</span>
  <span class="ruby-constant">IO</span>.<span class="ruby-identifier">select</span>([<span class="ruby-identifier">io</span>])
  <span class="ruby-keyword">retry</span>
<span class="ruby-keyword">end</span>
</pre>

<p>Although <a href="IO.html#method-i-read_nonblock"><code>IO#read_nonblock</code></a> doesn’t raise <a href="IO/WaitWritable.html"><code>IO::WaitWritable</code></a>. OpenSSL::Buffering#read_nonblock can raise <a href="IO/WaitWritable.html"><code>IO::WaitWritable</code></a>. If <a href="IO.html"><code>IO</code></a> and SSL should be used polymorphically, <a href="IO/WaitWritable.html"><code>IO::WaitWritable</code></a> should be rescued too. See the document of OpenSSL::Buffering#read_nonblock for sample code.</p>

<p>Note that this method is identical to readpartial except the non-blocking flag is set.</p>

<p>By specifying a keyword argument <em>exception</em> to <code>false</code>, you can indicate that <a href="IO.html#method-i-read_nonblock"><code>read_nonblock</code></a> should not raise an <a href="IO/WaitReadable.html"><code>IO::WaitReadable</code></a> exception, but return the symbol <code>:wait_readable</code> instead. At EOF, it will return nil instead of raising <a href="EOFError.html"><code>EOFError</code></a>.</p>

                              <div class="method-source-code" id="read_nonblock-source">
            <pre><span class="ruby-comment"># File ruby_3_3_0_preview2/io.rb, line 62</span>
<span class="ruby-keyword">def</span> <span class="ruby-identifier ruby-title">read_nonblock</span>(<span class="ruby-identifier">len</span>, <span class="ruby-identifier">buf</span> = <span class="ruby-keyword">nil</span>, <span class="ruby-value">exception:</span> <span class="ruby-keyword">true</span>)
  <span class="ruby-constant">Primitive</span>.<span class="ruby-identifier">io_read_nonblock</span>(<span class="ruby-identifier">len</span>, <span class="ruby-identifier">buf</span>, <span class="ruby-identifier">exception</span>)
<span class="ruby-keyword">end</span></pre>
                              </div>
                            </div>


                          </div>

                  <div id="method-i-readbyte" class="method-detail ">
                      <div class="method-heading">
                        <span class="method-callseq">
                          readbyte &rarr; integer
                              </span>
                              <span class="method-click-advice">click to toggle source</span>
                            </div>

                            <div class="method-description">
                              <p>Reads and returns the next byte (in range 0..255) from the stream; raises <a href="EOFError.html"><code>EOFError</code></a> if already at end-of-stream. See <a href="IO.html#class-IO-label-Byte+IO">Byte IO</a>.</p>

<pre class="ruby"><span class="ruby-identifier">f</span> = <span class="ruby-constant">File</span>.<span class="ruby-identifier">open</span>(<span class="ruby-string">&#39;t.txt&#39;</span>)
<span class="ruby-identifier">f</span>.<span class="ruby-identifier">readbyte</span> <span class="ruby-comment"># =&gt; 70</span>
<span class="ruby-identifier">f</span>.<span class="ruby-identifier">close</span>
<span class="ruby-identifier">f</span> = <span class="ruby-constant">File</span>.<span class="ruby-identifier">open</span>(<span class="ruby-string">&#39;t.rus&#39;</span>)
<span class="ruby-identifier">f</span>.<span class="ruby-identifier">readbyte</span> <span class="ruby-comment"># =&gt; 209</span>
<span class="ruby-identifier">f</span>.<span class="ruby-identifier">close</span>
</pre>

<p>Related: <a href="IO.html#method-i-getbyte"><code>IO#getbyte</code></a> (will not raise <a href="EOFError.html"><code>EOFError</code></a>).</p>

                              <div class="method-source-code" id="readbyte-source">
            <pre>static VALUE
rb_io_readbyte(VALUE io)
{
    VALUE c = rb_io_getbyte(io);

    if (NIL_P(c)) {
        rb_eof_error();
    }
    return c;
}</pre>
                              </div>
                            </div>


                          </div>

                  <div id="method-i-readchar" class="method-detail ">
                      <div class="method-heading">
                        <span class="method-callseq">
                          readchar &rarr; string
                              </span>
                              <span class="method-click-advice">click to toggle source</span>
                            </div>

                            <div class="method-description">
                              <p>Reads and returns the next 1-character string from the stream; raises <a href="EOFError.html"><code>EOFError</code></a> if already at end-of-stream. See <a href="IO.html#class-IO-label-Character+IO">Character IO</a>.</p>

<pre class="ruby"><span class="ruby-identifier">f</span> = <span class="ruby-constant">File</span>.<span class="ruby-identifier">open</span>(<span class="ruby-string">&#39;t.txt&#39;</span>)
<span class="ruby-identifier">f</span>.<span class="ruby-identifier">readchar</span>     <span class="ruby-comment"># =&gt; &quot;F&quot;</span>
<span class="ruby-identifier">f</span>.<span class="ruby-identifier">close</span>
<span class="ruby-identifier">f</span> = <span class="ruby-constant">File</span>.<span class="ruby-identifier">open</span>(<span class="ruby-string">&#39;t.rus&#39;</span>)
<span class="ruby-identifier">f</span>.<span class="ruby-identifier">readchar</span>.<span class="ruby-identifier">ord</span> <span class="ruby-comment"># =&gt; 1090</span>
<span class="ruby-identifier">f</span>.<span class="ruby-identifier">close</span>
</pre>

<p>Related:  <a href="IO.html#method-i-getc"><code>IO#getc</code></a> (will not raise <a href="EOFError.html"><code>EOFError</code></a>).</p>

                              <div class="method-source-code" id="readchar-source">
            <pre>static VALUE
rb_io_readchar(VALUE io)
{
    VALUE c = rb_io_getc(io);

    if (NIL_P(c)) {
        rb_eof_error();
    }
    return c;
}</pre>
                              </div>
                            </div>


                          </div>

                  <div id="method-i-readline" class="method-detail ">
                      <div class="method-heading">
                        <span class="method-callseq">
                          readline(sep = $/, chomp: false)   &rarr; string
                              </span>
                              <span class="method-click-advice">click to toggle source</span>
                            </div>
                      <div class="method-heading">
                        <span class="method-callseq">
                          readline(limit, chomp: false)      &rarr; string
                              </span>
                            </div>
                      <div class="method-heading">
                        <span class="method-callseq">
                          readline(sep, limit, chomp: false) &rarr; string
                              </span>
                            </div>

                            <div class="method-description">
                              <p>Reads a line as with <a href="IO.html#method-i-gets"><code>IO#gets</code></a>, but raises <a href="EOFError.html"><code>EOFError</code></a> if already at end-of-stream.</p>

<p>Optional keyword argument <code>chomp</code> specifies whether line separators are to be omitted.</p>

                              <div class="method-source-code" id="readline-source">
            <pre>static VALUE
rb_io_readline(int argc, VALUE *argv, VALUE io)
{
    VALUE line = rb_io_gets_m(argc, argv, io);

    if (NIL_P(line)) {
        rb_eof_error();
    }
    return line;
}</pre>
                              </div>
                            </div>


                          </div>

                  <div id="method-i-readlines" class="method-detail ">
                      <div class="method-heading">
                        <span class="method-callseq">
                          readlines(sep = $/, chomp: false)   &rarr; array
                              </span>
                              <span class="method-click-advice">click to toggle source</span>
                            </div>
                      <div class="method-heading">
                        <span class="method-callseq">
                          readlines(limit, chomp: false)       &rarr; array
                              </span>
                            </div>
                      <div class="method-heading">
                        <span class="method-callseq">
                          readlines(sep, limit, chomp: false) &rarr; array
                              </span>
                            </div>

                            <div class="method-description">
                              <p>Reads and returns all remaining line from the stream; does not modify <code>$_</code>. See <a href="IO.html#class-IO-label-Line+IO">Line IO</a>.</p>

<p>With no arguments given, returns lines as determined by line separator <code>$/</code>, or <code>nil</code> if none:</p>

<pre class="ruby"><span class="ruby-identifier">f</span> = <span class="ruby-constant">File</span>.<span class="ruby-identifier">new</span>(<span class="ruby-string">&#39;t.txt&#39;</span>)
<span class="ruby-identifier">f</span>.<span class="ruby-identifier">readlines</span>
<span class="ruby-comment"># =&gt; [&quot;First line\n&quot;, &quot;Second line\n&quot;, &quot;\n&quot;, &quot;Fourth line\n&quot;, &quot;Fifth line\n&quot;]</span>
<span class="ruby-identifier">f</span>.<span class="ruby-identifier">readlines</span> <span class="ruby-comment"># =&gt; []</span>
<span class="ruby-identifier">f</span>.<span class="ruby-identifier">close</span>
</pre>

<p>With only string argument <code>sep</code> given, returns lines as determined by line separator <code>sep</code>, or <code>nil</code> if none; see <a href="IO.html#class-IO-label-Line+Separator">Line Separator</a>:</p>

<pre class="ruby"><span class="ruby-identifier">f</span> = <span class="ruby-constant">File</span>.<span class="ruby-identifier">new</span>(<span class="ruby-string">&#39;t.txt&#39;</span>)
<span class="ruby-identifier">f</span>.<span class="ruby-identifier">readlines</span>(<span class="ruby-string">&#39;li&#39;</span>)
<span class="ruby-comment"># =&gt; [&quot;First li&quot;, &quot;ne\nSecond li&quot;, &quot;ne\n\nFourth li&quot;, &quot;ne\nFifth li&quot;, &quot;ne\n&quot;]</span>
<span class="ruby-identifier">f</span>.<span class="ruby-identifier">close</span>
</pre>

<p>The two special values for <code>sep</code> are honored:</p>

<pre class="ruby"><span class="ruby-identifier">f</span> = <span class="ruby-constant">File</span>.<span class="ruby-identifier">new</span>(<span class="ruby-string">&#39;t.txt&#39;</span>)
<span class="ruby-comment"># Get all into one string.</span>
<span class="ruby-identifier">f</span>.<span class="ruby-identifier">readlines</span>(<span class="ruby-keyword">nil</span>)
<span class="ruby-comment"># =&gt; [&quot;First line\nSecond line\n\nFourth line\nFifth line\n&quot;]</span>
<span class="ruby-comment"># Get paragraphs (up to two line separators).</span>
<span class="ruby-identifier">f</span>.<span class="ruby-identifier">rewind</span>
<span class="ruby-identifier">f</span>.<span class="ruby-identifier">readlines</span>(<span class="ruby-string">&#39;&#39;</span>)
<span class="ruby-comment"># =&gt; [&quot;First line\nSecond line\n\n&quot;, &quot;Fourth line\nFifth line\n&quot;]</span>
<span class="ruby-identifier">f</span>.<span class="ruby-identifier">close</span>
</pre>

<p>With only integer argument <code>limit</code> given, limits the number of bytes in each line; see <a href="IO.html#class-IO-label-Line+Limit">Line Limit</a>:</p>

<pre class="ruby"><span class="ruby-identifier">f</span> = <span class="ruby-constant">File</span>.<span class="ruby-identifier">new</span>(<span class="ruby-string">&#39;t.txt&#39;</span>)
<span class="ruby-identifier">f</span>.<span class="ruby-identifier">readlines</span>(<span class="ruby-value">8</span>)
<span class="ruby-comment"># =&gt; [&quot;First li&quot;, &quot;ne\n&quot;, &quot;Second l&quot;, &quot;ine\n&quot;, &quot;\n&quot;, &quot;Fourth l&quot;, &quot;ine\n&quot;, &quot;Fifth li&quot;, &quot;ne\n&quot;]</span>
<span class="ruby-identifier">f</span>.<span class="ruby-identifier">close</span>
</pre>

<p>With arguments <code>sep</code> and <code>limit</code> given, combines the two behaviors:</p>
<ul><li>
<p>Returns lines as determined by line separator <code>sep</code>.</p>
</li><li>
<p>But returns no more bytes in a line than are allowed by the limit.</p>
</li></ul>

<p>Optional keyword argument <code>chomp</code> specifies whether line separators are to be omitted:</p>

<pre class="ruby"><span class="ruby-identifier">f</span> = <span class="ruby-constant">File</span>.<span class="ruby-identifier">new</span>(<span class="ruby-string">&#39;t.txt&#39;</span>)
<span class="ruby-identifier">f</span>.<span class="ruby-identifier">readlines</span>(<span class="ruby-value">chomp:</span> <span class="ruby-keyword">true</span>)
<span class="ruby-comment"># =&gt; [&quot;First line&quot;, &quot;Second line&quot;, &quot;&quot;, &quot;Fourth line&quot;, &quot;Fifth line&quot;]</span>
<span class="ruby-identifier">f</span>.<span class="ruby-identifier">close</span>
</pre>

                              <div class="method-source-code" id="readlines-source">
            <pre>static VALUE
rb_io_readlines(int argc, VALUE *argv, VALUE io)
{
    struct getline_arg args;

    prepare_getline_args(argc, argv, &amp;args, io);
    return io_readlines(&amp;args, io);
}</pre>
                              </div>
                            </div>


                          </div>

                  <div id="method-i-readpartial" class="method-detail ">
                      <div class="method-heading">
                        <span class="method-callseq">
                          readpartial(maxlen)             &rarr; string
                              </span>
                              <span class="method-click-advice">click to toggle source</span>
                            </div>
                      <div class="method-heading">
                        <span class="method-callseq">
                          readpartial(maxlen, out_string) &rarr; out_string
                              </span>
                            </div>

                            <div class="method-description">
                              <p>Reads up to <code>maxlen</code> bytes from the stream; returns a string (either a new string or the given <code>out_string</code>). Its encoding is:</p>
<ul><li>
<p>The unchanged encoding of <code>out_string</code>, if <code>out_string</code> is given.</p>
</li><li>
<p>ASCII-8BIT, otherwise.</p>
</li><li>
<p>Contains <code>maxlen</code> bytes from the stream, if available.</p>
</li><li>
<p>Otherwise contains all available bytes, if any available.</p>
</li><li>
<p>Otherwise is an empty string.</p>
</li></ul>

<p>With the single non-negative integer argument <code>maxlen</code> given, returns a new string:</p>

<pre class="ruby"><span class="ruby-identifier">f</span> = <span class="ruby-constant">File</span>.<span class="ruby-identifier">new</span>(<span class="ruby-string">&#39;t.txt&#39;</span>)
<span class="ruby-identifier">f</span>.<span class="ruby-identifier">readpartial</span>(<span class="ruby-value">20</span>) <span class="ruby-comment"># =&gt; &quot;First line\nSecond l&quot;</span>
<span class="ruby-identifier">f</span>.<span class="ruby-identifier">readpartial</span>(<span class="ruby-value">20</span>) <span class="ruby-comment"># =&gt; &quot;ine\n\nFourth line\n&quot;</span>
<span class="ruby-identifier">f</span>.<span class="ruby-identifier">readpartial</span>(<span class="ruby-value">20</span>) <span class="ruby-comment"># =&gt; &quot;Fifth line\n&quot;</span>
<span class="ruby-identifier">f</span>.<span class="ruby-identifier">readpartial</span>(<span class="ruby-value">20</span>) <span class="ruby-comment"># Raises EOFError.</span>
<span class="ruby-identifier">f</span>.<span class="ruby-identifier">close</span>
</pre>

<p>With both argument <code>maxlen</code> and string argument <code>out_string</code> given, returns modified <code>out_string</code>:</p>

<pre class="ruby"><span class="ruby-identifier">f</span> = <span class="ruby-constant">File</span>.<span class="ruby-identifier">new</span>(<span class="ruby-string">&#39;t.txt&#39;</span>)
<span class="ruby-identifier">s</span> = <span class="ruby-string">&#39;foo&#39;</span>
<span class="ruby-identifier">f</span>.<span class="ruby-identifier">readpartial</span>(<span class="ruby-value">20</span>, <span class="ruby-identifier">s</span>) <span class="ruby-comment"># =&gt; &quot;First line\nSecond l&quot;</span>
<span class="ruby-identifier">s</span> = <span class="ruby-string">&#39;bar&#39;</span>
<span class="ruby-identifier">f</span>.<span class="ruby-identifier">readpartial</span>(<span class="ruby-value">0</span>, <span class="ruby-identifier">s</span>)  <span class="ruby-comment"># =&gt; &quot;&quot;</span>
<span class="ruby-identifier">f</span>.<span class="ruby-identifier">close</span>
</pre>

<p>This method is useful for a stream such as a pipe, a socket, or a tty. It blocks only when no data is immediately available. This means that it blocks only when <em>all</em> of the following are true:</p>
<ul><li>
<p>The byte buffer in the stream is empty.</p>
</li><li>
<p>The content of the stream is empty.</p>
</li><li>
<p>The stream is not at EOF.</p>
</li></ul>

<p>When blocked, the method waits for either more data or EOF on the stream:</p>
<ul><li>
<p>If more data is read, the method returns the data.</p>
</li><li>
<p>If EOF is reached, the method raises <a href="EOFError.html"><code>EOFError</code></a>.</p>
</li></ul>

<p>When not blocked, the method responds immediately:</p>
<ul><li>
<p>Returns data from the buffer if there is any.</p>
</li><li>
<p>Otherwise returns data from the stream if there is any.</p>
</li><li>
<p>Otherwise raises <a href="EOFError.html"><code>EOFError</code></a> if the stream has reached EOF.</p>
</li></ul>

<p>Note that this method is similar to sysread. The differences are:</p>
<ul><li>
<p>If the byte buffer is not empty, read from the byte buffer instead of “sysread for buffered <a href="IO.html"><code>IO</code></a> (<a href="IOError.html"><code>IOError</code></a>)”.</p>
</li><li>
<p>It doesn’t cause Errno::EWOULDBLOCK and Errno::EINTR.  When readpartial meets EWOULDBLOCK and EINTR by read system call, readpartial retries the system call.</p>
</li></ul>

<p>The latter means that readpartial is non-blocking-flag insensitive. It blocks on the situation <a href="IO.html#method-i-sysread"><code>IO#sysread</code></a> causes Errno::EWOULDBLOCK as if the fd is blocking mode.</p>

<p>Examples:</p>

<pre class="ruby"><span class="ruby-comment">#                        # Returned      Buffer Content    Pipe Content</span>
<span class="ruby-identifier">r</span>, <span class="ruby-identifier">w</span> = <span class="ruby-constant">IO</span>.<span class="ruby-identifier">pipe</span>           <span class="ruby-comment">#</span>
<span class="ruby-identifier">w</span> <span class="ruby-operator">&lt;&lt;</span> <span class="ruby-string">&#39;abc&#39;</span>               <span class="ruby-comment">#               &quot;&quot;                &quot;abc&quot;.</span>
<span class="ruby-identifier">r</span>.<span class="ruby-identifier">readpartial</span>(<span class="ruby-value">4096</span>)      <span class="ruby-comment"># =&gt; &quot;abc&quot;      &quot;&quot;                &quot;&quot;</span>
<span class="ruby-identifier">r</span>.<span class="ruby-identifier">readpartial</span>(<span class="ruby-value">4096</span>)      <span class="ruby-comment"># (Blocks because buffer and pipe are empty.)</span>

<span class="ruby-comment">#                        # Returned      Buffer Content    Pipe Content</span>
<span class="ruby-identifier">r</span>, <span class="ruby-identifier">w</span> = <span class="ruby-constant">IO</span>.<span class="ruby-identifier">pipe</span>           <span class="ruby-comment">#</span>
<span class="ruby-identifier">w</span> <span class="ruby-operator">&lt;&lt;</span> <span class="ruby-string">&#39;abc&#39;</span>               <span class="ruby-comment">#               &quot;&quot;                &quot;abc&quot;</span>
<span class="ruby-identifier">w</span>.<span class="ruby-identifier">close</span>                  <span class="ruby-comment">#               &quot;&quot;                &quot;abc&quot; EOF</span>
<span class="ruby-identifier">r</span>.<span class="ruby-identifier">readpartial</span>(<span class="ruby-value">4096</span>)      <span class="ruby-comment"># =&gt; &quot;abc&quot;      &quot;&quot;                 EOF</span>
<span class="ruby-identifier">r</span>.<span class="ruby-identifier">readpartial</span>(<span class="ruby-value">4096</span>)      <span class="ruby-comment"># raises EOFError</span>

<span class="ruby-comment">#                        # Returned      Buffer Content    Pipe Content</span>
<span class="ruby-identifier">r</span>, <span class="ruby-identifier">w</span> = <span class="ruby-constant">IO</span>.<span class="ruby-identifier">pipe</span>           <span class="ruby-comment">#</span>
<span class="ruby-identifier">w</span> <span class="ruby-operator">&lt;&lt;</span> <span class="ruby-string">&quot;abc\ndef\n&quot;</span>        <span class="ruby-comment">#               &quot;&quot;                &quot;abc\ndef\n&quot;</span>
<span class="ruby-identifier">r</span>.<span class="ruby-identifier">gets</span>                   <span class="ruby-comment"># =&gt; &quot;abc\n&quot;    &quot;def\n&quot;           &quot;&quot;</span>
<span class="ruby-identifier">w</span> <span class="ruby-operator">&lt;&lt;</span> <span class="ruby-string">&quot;ghi\n&quot;</span>             <span class="ruby-comment">#               &quot;def\n&quot;           &quot;ghi\n&quot;</span>
<span class="ruby-identifier">r</span>.<span class="ruby-identifier">readpartial</span>(<span class="ruby-value">4096</span>)      <span class="ruby-comment"># =&gt; &quot;def\n&quot;    &quot;&quot;                &quot;ghi\n&quot;</span>
<span class="ruby-identifier">r</span>.<span class="ruby-identifier">readpartial</span>(<span class="ruby-value">4096</span>)      <span class="ruby-comment"># =&gt; &quot;ghi\n&quot;    &quot;&quot;                &quot;&quot;</span>
</pre>

                              <div class="method-source-code" id="readpartial-source">
            <pre>static VALUE
io_readpartial(int argc, VALUE *argv, VALUE io)
{
    VALUE ret;

    ret = io_getpartial(argc, argv, io, Qnil, 0);
    if (NIL_P(ret))
        rb_eof_error();
    return ret;
}</pre>
                              </div>
                            </div>


                          </div>

                  <div id="method-i-reopen" class="method-detail ">
                      <div class="method-heading">
                        <span class="method-callseq">
                          reopen(other_io)                 &rarr; self
                              </span>
                              <span class="method-click-advice">click to toggle source</span>
                            </div>
                      <div class="method-heading">
                        <span class="method-callseq">
                          reopen(path, mode = &#39;r&#39;, **opts) &rarr; self
                              </span>
                            </div>

                            <div class="method-description">
                              <p>Reassociates the stream with another stream, which may be of a different class. This method may be used to redirect an existing stream to a new destination.</p>

<p>With argument <code>other_io</code> given, reassociates with that stream:</p>

<pre class="ruby"><span class="ruby-comment"># Redirect $stdin from a file.</span>
<span class="ruby-identifier">f</span> = <span class="ruby-constant">File</span>.<span class="ruby-identifier">open</span>(<span class="ruby-string">&#39;t.txt&#39;</span>)
<span class="ruby-identifier">$stdin</span>.<span class="ruby-identifier">reopen</span>(<span class="ruby-identifier">f</span>)
<span class="ruby-identifier">f</span>.<span class="ruby-identifier">close</span>

<span class="ruby-comment"># Redirect $stdout to a file.</span>
<span class="ruby-identifier">f</span> = <span class="ruby-constant">File</span>.<span class="ruby-identifier">open</span>(<span class="ruby-string">&#39;t.tmp&#39;</span>, <span class="ruby-string">&#39;w&#39;</span>)
<span class="ruby-identifier">$stdout</span>.<span class="ruby-identifier">reopen</span>(<span class="ruby-identifier">f</span>)
<span class="ruby-identifier">f</span>.<span class="ruby-identifier">close</span>
</pre>

<p>With argument <code>path</code> given, reassociates with a new stream to that file path:</p>

<pre class="ruby"><span class="ruby-identifier">$stdin</span>.<span class="ruby-identifier">reopen</span>(<span class="ruby-string">&#39;t.txt&#39;</span>)
<span class="ruby-identifier">$stdout</span>.<span class="ruby-identifier">reopen</span>(<span class="ruby-string">&#39;t.tmp&#39;</span>, <span class="ruby-string">&#39;w&#39;</span>)
</pre>

<p>Optional keyword arguments <code>opts</code> specify:</p>
<ul><li>
<p><a href="IO.html#class-IO-label-Open+Options">Open Options</a>.</p>
</li><li>
<p><a href="encodings_rdoc.html#label-Encoding+Options">Encoding options</a>.</p>
</li></ul>

                              <div class="method-source-code" id="reopen-source">
            <pre>static VALUE
rb_io_reopen(int argc, VALUE *argv, VALUE file)
{
    VALUE fname, nmode, opt;
    int oflags;
    rb_io_t *fptr;

    if (rb_scan_args(argc, argv, &quot;11:&quot;, &amp;fname, &amp;nmode, &amp;opt) == 1) {
        VALUE tmp = rb_io_check_io(fname);
        if (!NIL_P(tmp)) {
            return io_reopen(file, tmp);
        }
    }

    FilePathValue(fname);
    rb_io_taint_check(file);
    fptr = RFILE(file)-&gt;fptr;
    if (!fptr) {
        fptr = RFILE(file)-&gt;fptr = ZALLOC(rb_io_t);
    }

    if (!NIL_P(nmode) || !NIL_P(opt)) {
        int fmode;
        struct rb_io_encoding convconfig;

        rb_io_extract_modeenc(&amp;nmode, 0, opt, &amp;oflags, &amp;fmode, &amp;convconfig);
        if (RUBY_IO_EXTERNAL_P(fptr) &amp;&amp;
            ((fptr-&gt;mode &amp; FMODE_READWRITE) &amp; (fmode &amp; FMODE_READWRITE)) !=
            (fptr-&gt;mode &amp; FMODE_READWRITE)) {
            rb_raise(rb_eArgError,
                     &quot;%s can&#39;t change access mode from \&quot;%s\&quot; to \&quot;%s\&quot;&quot;,
                     PREP_STDIO_NAME(fptr), rb_io_fmode_modestr(fptr-&gt;mode),
                     rb_io_fmode_modestr(fmode));
        }
        fptr-&gt;mode = fmode;
        fptr-&gt;encs = convconfig;
    }
    else {
        oflags = rb_io_fmode_oflags(fptr-&gt;mode);
    }

    fptr-&gt;pathv = fname;
    if (fptr-&gt;fd &lt; 0) {
        fptr-&gt;fd = rb_sysopen(fptr-&gt;pathv, oflags, 0666);
        fptr-&gt;stdio_file = 0;
        return file;
    }

    if (fptr-&gt;mode &amp; FMODE_WRITABLE) {
        if (io_fflush(fptr) &lt; 0)
            rb_sys_fail_on_write(fptr);
    }
    fptr-&gt;rbuf.off = fptr-&gt;rbuf.len = 0;

    if (fptr-&gt;stdio_file) {
        int e = rb_freopen(rb_str_encode_ospath(fptr-&gt;pathv),
                           rb_io_oflags_modestr(oflags),
                           fptr-&gt;stdio_file);
        if (e) rb_syserr_fail_path(e, fptr-&gt;pathv);
        fptr-&gt;fd = fileno(fptr-&gt;stdio_file);
        rb_fd_fix_cloexec(fptr-&gt;fd);
#ifdef USE_SETVBUF
        if (setvbuf(fptr-&gt;stdio_file, NULL, _IOFBF, 0) != 0)
            rb_warn(&quot;setvbuf() can&#39;t be honoured for %&quot;PRIsVALUE, fptr-&gt;pathv);
#endif
        if (fptr-&gt;stdio_file == stderr) {
            if (setvbuf(fptr-&gt;stdio_file, NULL, _IONBF, BUFSIZ) != 0)
                rb_warn(&quot;setvbuf() can&#39;t be honoured for %&quot;PRIsVALUE, fptr-&gt;pathv);
        }
        else if (fptr-&gt;stdio_file == stdout &amp;&amp; isatty(fptr-&gt;fd)) {
            if (setvbuf(fptr-&gt;stdio_file, NULL, _IOLBF, BUFSIZ) != 0)
                rb_warn(&quot;setvbuf() can&#39;t be honoured for %&quot;PRIsVALUE, fptr-&gt;pathv);
        }
    }
    else {
        int tmpfd = rb_sysopen(fptr-&gt;pathv, oflags, 0666);
        int err = 0;
        if (rb_cloexec_dup2(tmpfd, fptr-&gt;fd) &lt; 0)
            err = errno;
        (void)close(tmpfd);
        if (err) {
            rb_syserr_fail_path(err, fptr-&gt;pathv);
        }
    }

    return file;
}</pre>
                              </div>
                            </div>


                          </div>

                  <div id="method-i-rewind" class="method-detail ">
                      <div class="method-heading">
                        <span class="method-callseq">
                          rewind &rarr; 0
                              </span>
                              <span class="method-click-advice">click to toggle source</span>
                            </div>

                            <div class="method-description">
                              <p>Repositions the stream to its beginning, setting both the position and the line number to zero; see <a href="IO.html#class-IO-label-Position">Position</a> and <a href="IO.html#class-IO-label-Line+Number">Line Number</a>:</p>

<pre class="ruby"><span class="ruby-identifier">f</span> = <span class="ruby-constant">File</span>.<span class="ruby-identifier">open</span>(<span class="ruby-string">&#39;t.txt&#39;</span>)
<span class="ruby-identifier">f</span>.<span class="ruby-identifier">tell</span>     <span class="ruby-comment"># =&gt; 0</span>
<span class="ruby-identifier">f</span>.<span class="ruby-identifier">lineno</span>   <span class="ruby-comment"># =&gt; 0</span>
<span class="ruby-identifier">f</span>.<span class="ruby-identifier">gets</span>     <span class="ruby-comment"># =&gt; &quot;First line\n&quot;</span>
<span class="ruby-identifier">f</span>.<span class="ruby-identifier">tell</span>     <span class="ruby-comment"># =&gt; 12</span>
<span class="ruby-identifier">f</span>.<span class="ruby-identifier">lineno</span>   <span class="ruby-comment"># =&gt; 1</span>
<span class="ruby-identifier">f</span>.<span class="ruby-identifier">rewind</span>   <span class="ruby-comment"># =&gt; 0</span>
<span class="ruby-identifier">f</span>.<span class="ruby-identifier">tell</span>     <span class="ruby-comment"># =&gt; 0</span>
<span class="ruby-identifier">f</span>.<span class="ruby-identifier">lineno</span>   <span class="ruby-comment"># =&gt; 0</span>
<span class="ruby-identifier">f</span>.<span class="ruby-identifier">close</span>
</pre>

<p>Note that this method cannot be used with streams such as pipes, ttys, and sockets.</p>

                              <div class="method-source-code" id="rewind-source">
            <pre>static VALUE
rb_io_rewind(VALUE io)
{
    rb_io_t *fptr;

    GetOpenFile(io, fptr);
    if (io_seek(fptr, 0L, 0) &lt; 0 &amp;&amp; errno) rb_sys_fail_path(fptr-&gt;pathv);
    if (io == ARGF.current_file) {
        ARGF.lineno -= fptr-&gt;lineno;
    }
    fptr-&gt;lineno = 0;
    if (fptr-&gt;readconv) {
        clear_readconv(fptr);
    }

    return INT2FIX(0);
}</pre>
                              </div>
                            </div>


                          </div>

                  <div id="method-i-seek" class="method-detail ">
                      <div class="method-heading">
                        <span class="method-callseq">
                          seek(offset, whence = IO::SEEK_SET) &rarr; 0
                              </span>
                              <span class="method-click-advice">click to toggle source</span>
                            </div>

                            <div class="method-description">
                              <p>Seeks to the position given by integer <code>offset</code> (see <a href="IO.html#class-IO-label-Position">Position</a>) and constant <code>whence</code>, which is one of:</p>
<ul><li>
<p><code>:CUR</code> or <code>IO::SEEK_CUR</code>: Repositions the stream to its current position plus the given <code>offset</code>:</p>

<pre class="ruby"><span class="ruby-identifier">f</span> = <span class="ruby-constant">File</span>.<span class="ruby-identifier">open</span>(<span class="ruby-string">&#39;t.txt&#39;</span>)
<span class="ruby-identifier">f</span>.<span class="ruby-identifier">tell</span>            <span class="ruby-comment"># =&gt; 0</span>
<span class="ruby-identifier">f</span>.<span class="ruby-identifier">seek</span>(<span class="ruby-value">20</span>, <span class="ruby-value">:CUR</span>)  <span class="ruby-comment"># =&gt; 0</span>
<span class="ruby-identifier">f</span>.<span class="ruby-identifier">tell</span>            <span class="ruby-comment"># =&gt; 20</span>
<span class="ruby-identifier">f</span>.<span class="ruby-identifier">seek</span>(<span class="ruby-value">-10</span>, <span class="ruby-value">:CUR</span>) <span class="ruby-comment"># =&gt; 0</span>
<span class="ruby-identifier">f</span>.<span class="ruby-identifier">tell</span>            <span class="ruby-comment"># =&gt; 10</span>
<span class="ruby-identifier">f</span>.<span class="ruby-identifier">close</span>
</pre>
</li><li>
<p><code>:END</code> or <code>IO::SEEK_END</code>: Repositions the stream to its end plus the given <code>offset</code>:</p>

<pre class="ruby"><span class="ruby-identifier">f</span> = <span class="ruby-constant">File</span>.<span class="ruby-identifier">open</span>(<span class="ruby-string">&#39;t.txt&#39;</span>)
<span class="ruby-identifier">f</span>.<span class="ruby-identifier">tell</span>            <span class="ruby-comment"># =&gt; 0</span>
<span class="ruby-identifier">f</span>.<span class="ruby-identifier">seek</span>(<span class="ruby-value">0</span>, <span class="ruby-value">:END</span>)   <span class="ruby-comment"># =&gt; 0  # Repositions to stream end.</span>
<span class="ruby-identifier">f</span>.<span class="ruby-identifier">tell</span>            <span class="ruby-comment"># =&gt; 52</span>
<span class="ruby-identifier">f</span>.<span class="ruby-identifier">seek</span>(<span class="ruby-value">-20</span>, <span class="ruby-value">:END</span>) <span class="ruby-comment"># =&gt; 0</span>
<span class="ruby-identifier">f</span>.<span class="ruby-identifier">tell</span>            <span class="ruby-comment"># =&gt; 32</span>
<span class="ruby-identifier">f</span>.<span class="ruby-identifier">seek</span>(<span class="ruby-value">-40</span>, <span class="ruby-value">:END</span>) <span class="ruby-comment"># =&gt; 0</span>
<span class="ruby-identifier">f</span>.<span class="ruby-identifier">tell</span>            <span class="ruby-comment"># =&gt; 12</span>
<span class="ruby-identifier">f</span>.<span class="ruby-identifier">close</span>
</pre>
</li><li>
<p><code>:SET</code> or <code>IO:SEEK_SET</code>: Repositions the stream to the given <code>offset</code>:</p>

<pre class="ruby"><span class="ruby-identifier">f</span> = <span class="ruby-constant">File</span>.<span class="ruby-identifier">open</span>(<span class="ruby-string">&#39;t.txt&#39;</span>)
<span class="ruby-identifier">f</span>.<span class="ruby-identifier">tell</span>            <span class="ruby-comment"># =&gt; 0</span>
<span class="ruby-identifier">f</span>.<span class="ruby-identifier">seek</span>(<span class="ruby-value">20</span>, <span class="ruby-value">:SET</span>) <span class="ruby-comment"># =&gt; 0</span>
<span class="ruby-identifier">f</span>.<span class="ruby-identifier">tell</span>           <span class="ruby-comment"># =&gt; 20</span>
<span class="ruby-identifier">f</span>.<span class="ruby-identifier">seek</span>(<span class="ruby-value">40</span>, <span class="ruby-value">:SET</span>) <span class="ruby-comment"># =&gt; 0</span>
<span class="ruby-identifier">f</span>.<span class="ruby-identifier">tell</span>           <span class="ruby-comment"># =&gt; 40</span>
<span class="ruby-identifier">f</span>.<span class="ruby-identifier">close</span>
</pre>
</li></ul>

<p>Related: <a href="IO.html#method-i-pos-3D"><code>IO#pos=</code></a>, <a href="IO.html#method-i-tell"><code>IO#tell</code></a>.</p>

                              <div class="method-source-code" id="seek-source">
            <pre>static VALUE
rb_io_seek_m(int argc, VALUE *argv, VALUE io)
{
    VALUE offset, ptrname;
    int whence = SEEK_SET;

    if (rb_scan_args(argc, argv, &quot;11&quot;, &amp;offset, &amp;ptrname) == 2) {
        whence = interpret_seek_whence(ptrname);
    }

    return rb_io_seek(io, offset, whence);
}</pre>
                              </div>
                            </div>


                          </div>

                  <div id="method-i-set_encoding" class="method-detail ">
                      <div class="method-heading">
                        <span class="method-callseq">
                          set_encoding(ext_enc)                   &rarr; self
                              </span>
                              <span class="method-click-advice">click to toggle source</span>
                            </div>
                      <div class="method-heading">
                        <span class="method-callseq">
                          set_encoding(ext_enc, int_enc, **enc_opts)  &rarr; self
                              </span>
                            </div>
                      <div class="method-heading">
                        <span class="method-callseq">
                          set_encoding(&#39;ext_enc:int_enc&#39;, **enc_opts) &rarr; self
                              </span>
                            </div>

                            <div class="method-description">
                              <p>See <a href="File.html#class-File-label-Encodings">Encodings</a>.</p>

<p>Argument <code>ext_enc</code>, if given, must be an <a href="Encoding.html"><code>Encoding</code></a> object or a <a href="String.html"><code>String</code></a> with the encoding name; it is assigned as the encoding for the stream.</p>

<p>Argument <code>int_enc</code>, if given, must be an <a href="Encoding.html"><code>Encoding</code></a> object or a <a href="String.html"><code>String</code></a> with the encoding name; it is assigned as the encoding for the internal string.</p>

<p>Argument <code>&#39;ext_enc:int_enc&#39;</code>, if given, is a string containing two colon-separated encoding names; corresponding <a href="Encoding.html"><code>Encoding</code></a> objects are assigned as the external and internal encodings for the stream.</p>

<p>If the external encoding of a string is binary/ASCII-8BIT, the internal encoding of the string is set to nil, since no transcoding is needed.</p>

<p>Optional keyword arguments <code>enc_opts</code> specify <a href="encodings_rdoc.html#label-Encoding+Options">Encoding options</a>.</p>

                              <div class="method-source-code" id="set_encoding-source">
            <pre>static VALUE
rb_io_set_encoding(int argc, VALUE *argv, VALUE io)
{
    rb_io_t *fptr;
    VALUE v1, v2, opt;

    if (!RB_TYPE_P(io, T_FILE)) {
        return forward(io, id_set_encoding, argc, argv);
    }

    argc = rb_scan_args(argc, argv, &quot;11:&quot;, &amp;v1, &amp;v2, &amp;opt);
    GetOpenFile(io, fptr);
    io_encoding_set(fptr, v1, v2, opt);
    return io;
}</pre>
                              </div>
                            </div>


                          </div>

                  <div id="method-i-set_encoding_by_bom" class="method-detail ">
                      <div class="method-heading">
                        <span class="method-callseq">
                          set_encoding_by_bom &rarr; encoding or nil
                              </span>
                              <span class="method-click-advice">click to toggle source</span>
                            </div>

                            <div class="method-description">
                              <p>If the stream begins with a BOM (<a href="https://en.wikipedia.org/wiki/Byte_order_mark">byte order marker</a>), consumes the BOM and sets the external encoding accordingly; returns the result encoding if found, or <code>nil</code> otherwise:</p>

<pre class="ruby"><span class="ruby-constant">File</span>.<span class="ruby-identifier">write</span>(<span class="ruby-string">&#39;t.tmp&#39;</span>, <span class="ruby-string">&quot;\u{FEFF}abc&quot;</span>)
<span class="ruby-identifier">io</span> = <span class="ruby-constant">File</span>.<span class="ruby-identifier">open</span>(<span class="ruby-string">&#39;t.tmp&#39;</span>, <span class="ruby-string">&#39;rb&#39;</span>)
<span class="ruby-identifier">io</span>.<span class="ruby-identifier">set_encoding_by_bom</span> <span class="ruby-comment"># =&gt; #&lt;Encoding:UTF-8&gt;</span>
<span class="ruby-identifier">io</span>.<span class="ruby-identifier">close</span>

<span class="ruby-constant">File</span>.<span class="ruby-identifier">write</span>(<span class="ruby-string">&#39;t.tmp&#39;</span>, <span class="ruby-string">&#39;abc&#39;</span>)
<span class="ruby-identifier">io</span> = <span class="ruby-constant">File</span>.<span class="ruby-identifier">open</span>(<span class="ruby-string">&#39;t.tmp&#39;</span>, <span class="ruby-string">&#39;rb&#39;</span>)
<span class="ruby-identifier">io</span>.<span class="ruby-identifier">set_encoding_by_bom</span> <span class="ruby-comment"># =&gt; nil</span>
<span class="ruby-identifier">io</span>.<span class="ruby-identifier">close</span>
</pre>

<p>Raises an exception if the stream is not binmode or its encoding has already been set.</p>

                              <div class="method-source-code" id="set_encoding_by_bom-source">
            <pre>static VALUE
rb_io_set_encoding_by_bom(VALUE io)
{
    rb_io_t *fptr;

    GetOpenFile(io, fptr);
    if (!(fptr-&gt;mode &amp; FMODE_BINMODE)) {
        rb_raise(rb_eArgError, &quot;ASCII incompatible encoding needs binmode&quot;);
    }
    if (fptr-&gt;encs.enc2) {
        rb_raise(rb_eArgError, &quot;encoding conversion is set&quot;);
    }
    else if (fptr-&gt;encs.enc &amp;&amp; fptr-&gt;encs.enc != rb_ascii8bit_encoding()) {
        rb_raise(rb_eArgError, &quot;encoding is set to %s already&quot;,
                 rb_enc_name(fptr-&gt;encs.enc));
    }
    if (!io_set_encoding_by_bom(io)) return Qnil;
    return rb_enc_from_encoding(fptr-&gt;encs.enc);
}</pre>
                              </div>
                            </div>


                          </div>

                  <div id="method-i-stat" class="method-detail ">
                      <div class="method-heading">
                        <span class="method-callseq">
                          stat    &rarr; stat
                              </span>
                              <span class="method-click-advice">click to toggle source</span>
                            </div>

                            <div class="method-description">
                              <p>Returns status information for <em>ios</em> as an object of type <a href="File/Stat.html"><code>File::Stat</code></a>.</p>

<pre class="ruby"><span class="ruby-identifier">f</span> = <span class="ruby-constant">File</span>.<span class="ruby-identifier">new</span>(<span class="ruby-string">&quot;testfile&quot;</span>)
<span class="ruby-identifier">s</span> = <span class="ruby-identifier">f</span>.<span class="ruby-identifier">stat</span>
<span class="ruby-string">&quot;%o&quot;</span> <span class="ruby-operator">%</span> <span class="ruby-identifier">s</span>.<span class="ruby-identifier">mode</span>   <span class="ruby-comment">#=&gt; &quot;100644&quot;</span>
<span class="ruby-identifier">s</span>.<span class="ruby-identifier">blksize</span>       <span class="ruby-comment">#=&gt; 4096</span>
<span class="ruby-identifier">s</span>.<span class="ruby-identifier">atime</span>         <span class="ruby-comment">#=&gt; Wed Apr 09 08:53:54 CDT 2003</span>
</pre>

                              <div class="method-source-code" id="stat-source">
            <pre>static VALUE
rb_io_stat(VALUE obj)
{
    rb_io_t *fptr;
    struct stat st;

    GetOpenFile(obj, fptr);
    if (fstat(fptr-&gt;fd, &amp;st) == -1) {
        rb_sys_fail_path(fptr-&gt;pathv);
    }
    return rb_stat_new(&amp;st);
}</pre>
                              </div>
                            </div>


                          </div>

                  <div id="method-i-sync" class="method-detail ">
                      <div class="method-heading">
                        <span class="method-callseq">
                          sync &rarr; true or false
                              </span>
                              <span class="method-click-advice">click to toggle source</span>
                            </div>

                            <div class="method-description">
                              <p>Returns the current sync mode of the stream. When sync mode is true, all output is immediately flushed to the underlying operating system and is not buffered by Ruby internally. See also <a href="IO.html#method-i-fsync"><code>fsync</code></a>.</p>

<pre class="ruby"><span class="ruby-identifier">f</span> = <span class="ruby-constant">File</span>.<span class="ruby-identifier">open</span>(<span class="ruby-string">&#39;t.tmp&#39;</span>, <span class="ruby-string">&#39;w&#39;</span>)
<span class="ruby-identifier">f</span>.<span class="ruby-identifier">sync</span> <span class="ruby-comment"># =&gt; false</span>
<span class="ruby-identifier">f</span>.<span class="ruby-identifier">sync</span> = <span class="ruby-keyword">true</span>
<span class="ruby-identifier">f</span>.<span class="ruby-identifier">sync</span> <span class="ruby-comment"># =&gt; true</span>
<span class="ruby-identifier">f</span>.<span class="ruby-identifier">close</span>
</pre>

                              <div class="method-source-code" id="sync-source">
            <pre>static VALUE
rb_io_sync(VALUE io)
{
    rb_io_t *fptr;

    io = GetWriteIO(io);
    GetOpenFile(io, fptr);
    return RBOOL(fptr-&gt;mode &amp; FMODE_SYNC);
}</pre>
                              </div>
                            </div>


                          </div>

                  <div id="method-i-sync-3D" class="method-detail ">
                      <div class="method-heading">
                        <span class="method-callseq">
                          sync = boolean &rarr; boolean
                              </span>
                              <span class="method-click-advice">click to toggle source</span>
                            </div>

                            <div class="method-description">
                              <p>Sets the <em>sync</em> <em>mode</em> for the stream to the given value; returns the given value.</p>

<p>Values for the sync mode:</p>
<ul><li>
<p><code>true</code>: All output is immediately flushed to the underlying operating system and is not buffered internally.</p>
</li><li>
<p><code>false</code>: Output may be buffered internally.</p>
</li></ul>

<p>Example;</p>

<pre class="ruby"><span class="ruby-identifier">f</span> = <span class="ruby-constant">File</span>.<span class="ruby-identifier">open</span>(<span class="ruby-string">&#39;t.tmp&#39;</span>, <span class="ruby-string">&#39;w&#39;</span>)
<span class="ruby-identifier">f</span>.<span class="ruby-identifier">sync</span> <span class="ruby-comment"># =&gt; false</span>
<span class="ruby-identifier">f</span>.<span class="ruby-identifier">sync</span> = <span class="ruby-keyword">true</span>
<span class="ruby-identifier">f</span>.<span class="ruby-identifier">sync</span> <span class="ruby-comment"># =&gt; true</span>
<span class="ruby-identifier">f</span>.<span class="ruby-identifier">close</span>
</pre>

<p>Related: <a href="IO.html#method-i-fsync"><code>IO#fsync</code></a>.</p>

                              <div class="method-source-code" id="sync-3D-source">
            <pre>static VALUE
rb_io_set_sync(VALUE io, VALUE sync)
{
    rb_io_t *fptr;

    io = GetWriteIO(io);
    GetOpenFile(io, fptr);
    if (RTEST(sync)) {
        fptr-&gt;mode |= FMODE_SYNC;
    }
    else {
        fptr-&gt;mode &amp;= ~FMODE_SYNC;
    }
    return sync;
}</pre>
                              </div>
                            </div>


                          </div>

                  <div id="method-i-sysread" class="method-detail ">
                      <div class="method-heading">
                        <span class="method-callseq">
                          sysread(maxlen)             &rarr; string
                              </span>
                              <span class="method-click-advice">click to toggle source</span>
                            </div>
                      <div class="method-heading">
                        <span class="method-callseq">
                          sysread(maxlen, out_string) &rarr; string
                              </span>
                            </div>

                            <div class="method-description">
                              <p>Behaves like <a href="IO.html#method-i-readpartial"><code>IO#readpartial</code></a>, except that it uses low-level system functions.</p>

<p>This method should not be used with other stream-reader methods.</p>

                              <div class="method-source-code" id="sysread-source">
            <pre>static VALUE
rb_io_sysread(int argc, VALUE *argv, VALUE io)
{
    VALUE len, str;
    rb_io_t *fptr;
    long n, ilen;
    struct io_internal_read_struct iis;
    int shrinkable;

    rb_scan_args(argc, argv, &quot;11&quot;, &amp;len, &amp;str);
    ilen = NUM2LONG(len);

    shrinkable = io_setstrbuf(&amp;str, ilen);
    if (ilen == 0) return str;

    GetOpenFile(io, fptr);
    rb_io_check_byte_readable(fptr);

    if (READ_DATA_BUFFERED(fptr)) {
        rb_raise(rb_eIOError, &quot;sysread for buffered IO&quot;);
    }

    rb_io_check_closed(fptr);

    io_setstrbuf(&amp;str, ilen);
    iis.th = rb_thread_current();
    iis.fptr = fptr;
    iis.nonblock = 0;
    iis.fd = fptr-&gt;fd;
    iis.buf = RSTRING_PTR(str);
    iis.capa = ilen;
    iis.timeout = NULL;
    n = io_read_memory_locktmp(str, &amp;iis);

    if (n &lt; 0) {
        rb_sys_fail_path(fptr-&gt;pathv);
    }

    io_set_read_length(str, n, shrinkable);

    if (n == 0 &amp;&amp; ilen &gt; 0) {
        rb_eof_error();
    }

    return str;
}</pre>
                              </div>
                            </div>


                          </div>

                  <div id="method-i-sysseek" class="method-detail ">
                      <div class="method-heading">
                        <span class="method-callseq">
                          sysseek(offset, whence = IO::SEEK_SET) &rarr; integer
                              </span>
                              <span class="method-click-advice">click to toggle source</span>
                            </div>

                            <div class="method-description">
                              <p>Behaves like <a href="IO.html#method-i-seek"><code>IO#seek</code></a>, except that it:</p>
<ul><li>
<p>Uses low-level system functions.</p>
</li><li>
<p>Returns the new position.</p>
</li></ul>

                              <div class="method-source-code" id="sysseek-source">
            <pre>static VALUE
rb_io_sysseek(int argc, VALUE *argv, VALUE io)
{
    VALUE offset, ptrname;
    int whence = SEEK_SET;
    rb_io_t *fptr;
    rb_off_t pos;

    if (rb_scan_args(argc, argv, &quot;11&quot;, &amp;offset, &amp;ptrname) == 2) {
        whence = interpret_seek_whence(ptrname);
    }
    pos = NUM2OFFT(offset);
    GetOpenFile(io, fptr);
    if ((fptr-&gt;mode &amp; FMODE_READABLE) &amp;&amp;
        (READ_DATA_BUFFERED(fptr) || READ_CHAR_PENDING(fptr))) {
        rb_raise(rb_eIOError, &quot;sysseek for buffered IO&quot;);
    }
    if ((fptr-&gt;mode &amp; FMODE_WRITABLE) &amp;&amp; fptr-&gt;wbuf.len) {
        rb_warn(&quot;sysseek for buffered IO&quot;);
    }
    errno = 0;
    pos = lseek(fptr-&gt;fd, pos, whence);
    if (pos &lt; 0 &amp;&amp; errno) rb_sys_fail_path(fptr-&gt;pathv);

    return OFFT2NUM(pos);
}</pre>
                              </div>
                            </div>


                          </div>

                  <div id="method-i-syswrite" class="method-detail ">
                      <div class="method-heading">
                        <span class="method-callseq">
                          syswrite(object) &rarr; integer
                              </span>
                              <span class="method-click-advice">click to toggle source</span>
                            </div>

                            <div class="method-description">
                              <p>Writes the given <code>object</code> to self, which must be opened for writing (see Modes); returns the number bytes written. If <code>object</code> is not a string is converted via method to_s:</p>

<pre class="ruby"><span class="ruby-identifier">f</span> = <span class="ruby-constant">File</span>.<span class="ruby-identifier">new</span>(<span class="ruby-string">&#39;t.tmp&#39;</span>, <span class="ruby-string">&#39;w&#39;</span>)
<span class="ruby-identifier">f</span>.<span class="ruby-identifier">syswrite</span>(<span class="ruby-string">&#39;foo&#39;</span>) <span class="ruby-comment"># =&gt; 3</span>
<span class="ruby-identifier">f</span>.<span class="ruby-identifier">syswrite</span>(<span class="ruby-value">30</span>)    <span class="ruby-comment"># =&gt; 2</span>
<span class="ruby-identifier">f</span>.<span class="ruby-identifier">syswrite</span>(<span class="ruby-value">:foo</span>)  <span class="ruby-comment"># =&gt; 3</span>
<span class="ruby-identifier">f</span>.<span class="ruby-identifier">close</span>
</pre>

<p>This methods should not be used with other stream-writer methods.</p>

                              <div class="method-source-code" id="syswrite-source">
            <pre>static VALUE
rb_io_syswrite(VALUE io, VALUE str)
{
    VALUE tmp;
    rb_io_t *fptr;
    long n, len;
    const char *ptr;

    if (!RB_TYPE_P(str, T_STRING))
        str = rb_obj_as_string(str);

    io = GetWriteIO(io);
    GetOpenFile(io, fptr);
    rb_io_check_writable(fptr);

    if (fptr-&gt;wbuf.len) {
        rb_warn(&quot;syswrite for buffered IO&quot;);
    }

    tmp = rb_str_tmp_frozen_acquire(str);
    RSTRING_GETMEM(tmp, ptr, len);
    n = rb_io_write_memory(fptr, ptr, len);
    if (n &lt; 0) rb_sys_fail_path(fptr-&gt;pathv);
    rb_str_tmp_frozen_release(str, tmp);

    return LONG2FIX(n);
}</pre>
                              </div>
                            </div>


                          </div>

                  <div id="method-i-tell" class="method-detail ">
                      <div class="method-heading">
                        <span class="method-callseq">
                          tell &rarr; integer
                              </span>
                              <span class="method-click-advice">click to toggle source</span>
                            </div>

                            <div class="method-description">
                              <p>Returns the current position (in bytes) in <code>self</code> (see <a href="IO.html#class-IO-label-Position">Position</a>):</p>

<pre class="ruby"><span class="ruby-identifier">f</span> = <span class="ruby-constant">File</span>.<span class="ruby-identifier">open</span>(<span class="ruby-string">&#39;t.txt&#39;</span>)
<span class="ruby-identifier">f</span>.<span class="ruby-identifier">tell</span> <span class="ruby-comment"># =&gt; 0</span>
<span class="ruby-identifier">f</span>.<span class="ruby-identifier">gets</span> <span class="ruby-comment"># =&gt; &quot;First line\n&quot;</span>
<span class="ruby-identifier">f</span>.<span class="ruby-identifier">tell</span> <span class="ruby-comment"># =&gt; 12</span>
<span class="ruby-identifier">f</span>.<span class="ruby-identifier">close</span>
</pre>

<p>Related: <a href="IO.html#method-i-pos-3D"><code>IO#pos=</code></a>, <a href="IO.html#method-i-seek"><code>IO#seek</code></a>.</p>

                              <div class="method-source-code" id="tell-source">
            <pre>static VALUE
rb_io_tell(VALUE io)
{
    rb_io_t *fptr;
    rb_off_t pos;

    GetOpenFile(io, fptr);
    pos = io_tell(fptr);
    if (pos &lt; 0 &amp;&amp; errno) rb_sys_fail_path(fptr-&gt;pathv);
    pos -= fptr-&gt;rbuf.len;
    return OFFT2NUM(pos);
}</pre>
                              </div>
                            </div>

                            <div class="aliases">
                              Also aliased as: <a href="IO.html#method-i-pos">pos</a>
                            </div>

                          </div>

                  <div id="method-i-timeout" class="method-detail ">
                      <div class="method-heading">
                        <span class="method-callseq">
                          timeout &rarr; duration or nil
                              </span>
                              <span class="method-click-advice">click to toggle source</span>
                            </div>

                            <div class="method-description">
                              <p>Get the internal timeout duration or nil if it was not set.</p>

                              <div class="method-source-code" id="timeout-source">
            <pre>VALUE
rb_io_timeout(VALUE self)
{
    rb_io_t *fptr = rb_io_get_fptr(self);

    return fptr-&gt;timeout;
}</pre>
                              </div>
                            </div>


                          </div>

                  <div id="method-i-timeout-3D" class="method-detail ">
                      <div class="method-heading">
                        <span class="method-callseq">
                          timeout = duration &rarr; duration
                              </span>
                              <span class="method-click-advice">click to toggle source</span>
                            </div>
                      <div class="method-heading">
                        <span class="method-callseq">
                          timeout = nil &rarr; nil
                              </span>
                            </div>

                            <div class="method-description">
                              <p>Sets the internal timeout to the specified duration or nil. The timeout applies to all blocking operations where possible.</p>

<p>When the operation performs longer than the timeout set, <a href="IO/TimeoutError.html"><code>IO::TimeoutError</code></a> is raised.</p>

<p>This affects the following methods (but is not limited to): <a href="IO.html#method-i-gets"><code>gets</code></a>, <a href="IO.html#method-i-puts"><code>puts</code></a>, <a href="IO.html#method-i-read"><code>read</code></a>, <a href="IO.html#method-i-write"><code>write</code></a>, <a href="IO.html#method-i-wait_readable"><code>wait_readable</code></a> and <a href="IO.html#method-i-wait_writable"><code>wait_writable</code></a>. This also affects blocking socket operations like Socket#accept and Socket#connect.</p>

<p>Some operations like <a href="Kernel.html#method-i-open"><code>File#open</code></a> and <a href="IO.html#method-i-close"><code>IO#close</code></a> are not affected by the timeout. A timeout during a write operation may leave the <a href="IO.html"><code>IO</code></a> in an inconsistent state, e.g. data was partially written. Generally speaking, a timeout is a last ditch effort to prevent an application from hanging on slow I/O operations, such as those that occur during a slowloris attack.</p>

                              <div class="method-source-code" id="timeout-3D-source">
            <pre>VALUE
rb_io_set_timeout(VALUE self, VALUE timeout)
{
    // Validate it:
    if (RTEST(timeout)) {
        rb_time_interval(timeout);
    }

    rb_io_t *fptr = rb_io_get_fptr(self);

    fptr-&gt;timeout = timeout;

    return self;
}</pre>
                              </div>
                            </div>


                          </div>

                  <div id="method-i-to_i" class="method-detail method-alias">
                            <div class="method-heading">
                              <span class="method-name">to_i</span><span
                                class="method-args">()</span>
                            </div>

                            <div class="method-description">
                              <p>Returns the integer file descriptor for the stream:</p>

<pre class="ruby"><span class="ruby-identifier">$stdin</span>.<span class="ruby-identifier">fileno</span>             <span class="ruby-comment"># =&gt; 0</span>
<span class="ruby-identifier">$stdout</span>.<span class="ruby-identifier">fileno</span>            <span class="ruby-comment"># =&gt; 1</span>
<span class="ruby-identifier">$stderr</span>.<span class="ruby-identifier">fileno</span>            <span class="ruby-comment"># =&gt; 2</span>
<span class="ruby-constant">File</span>.<span class="ruby-identifier">open</span>(<span class="ruby-string">&#39;t.txt&#39;</span>).<span class="ruby-identifier">fileno</span> <span class="ruby-comment"># =&gt; 10</span>
<span class="ruby-identifier">f</span>.<span class="ruby-identifier">close</span>
</pre>

                            </div>


                            <div class="aliases">
                              Alias for: <a href="IO.html#method-i-fileno">fileno</a>
                            </div>
                          </div>

                  <div id="method-i-to_io" class="method-detail ">
                      <div class="method-heading">
                        <span class="method-callseq">
                          to_io &rarr; self
                              </span>
                              <span class="method-click-advice">click to toggle source</span>
                            </div>

                            <div class="method-description">
                              <p>Returns <code>self</code>.</p>

                              <div class="method-source-code" id="to_io-source">
            <pre>static VALUE
rb_io_to_io(VALUE io)
{
    return io;
}</pre>
                              </div>
                            </div>


                          </div>

                  <div id="method-i-to_path" class="method-detail method-alias">
                            <div class="method-heading">
                              <span class="method-name">to_path</span><span
                                class="method-args">()</span>
                            </div>

                            <div class="method-description">
                              <p>Returns the path associated with the <a href="IO.html"><code>IO</code></a>, or <code>nil</code> if there is no path associated with the <a href="IO.html"><code>IO</code></a>. It is not guaranteed that the path exists on the filesystem.</p>

<pre class="ruby"><span class="ruby-identifier">$stdin</span>.<span class="ruby-identifier">path</span> <span class="ruby-comment"># =&gt; &quot;&lt;STDIN&gt;&quot;</span>

<span class="ruby-constant">File</span>.<span class="ruby-identifier">open</span>(<span class="ruby-string">&quot;testfile&quot;</span>) {<span class="ruby-operator">|</span><span class="ruby-identifier">f</span><span class="ruby-operator">|</span> <span class="ruby-identifier">f</span>.<span class="ruby-identifier">path</span>} <span class="ruby-comment"># =&gt; &quot;testfile&quot;</span>
</pre>

                            </div>


                            <div class="aliases">
                              Alias for: <a href="IO.html#method-i-path">path</a>
                            </div>
                          </div>

                  <div id="method-i-tty-3F" class="method-detail method-alias">
                            <div class="method-heading">
                              <span class="method-name">tty?</span><span
                                class="method-args">()</span>
                            </div>

                            <div class="method-description">
                              <p>Returns <code>true</code> if the stream is associated with a terminal device (tty), <code>false</code> otherwise:</p>

<pre class="ruby"><span class="ruby-identifier">f</span> = <span class="ruby-constant">File</span>.<span class="ruby-identifier">new</span>(<span class="ruby-string">&#39;t.txt&#39;</span>).<span class="ruby-identifier">isatty</span>    <span class="ruby-comment">#=&gt; false</span>
<span class="ruby-identifier">f</span>.<span class="ruby-identifier">close</span>
<span class="ruby-identifier">f</span> = <span class="ruby-constant">File</span>.<span class="ruby-identifier">new</span>(<span class="ruby-string">&#39;/dev/tty&#39;</span>).<span class="ruby-identifier">isatty</span> <span class="ruby-comment">#=&gt; true</span>
<span class="ruby-identifier">f</span>.<span class="ruby-identifier">close</span>
</pre>

                            </div>


                            <div class="aliases">
                              Alias for: <a href="IO.html#method-i-isatty">isatty</a>
                            </div>
                          </div>

                  <div id="method-i-ungetbyte" class="method-detail ">
                      <div class="method-heading">
                        <span class="method-callseq">
                          ungetbyte(integer) &rarr; nil
                              </span>
                              <span class="method-click-advice">click to toggle source</span>
                            </div>
                      <div class="method-heading">
                        <span class="method-callseq">
                          ungetbyte(string)  &rarr; nil
                              </span>
                            </div>

                            <div class="method-description">
                              <p>Pushes back (“unshifts”) the given data onto the stream’s buffer, placing the data so that it is next to be read; returns <code>nil</code>. See <a href="IO.html#class-IO-label-Byte+IO">Byte IO</a>.</p>

<p>Note that:</p>
<ul><li>
<p>Calling the method has no effect with unbuffered reads (such as <a href="IO.html#method-i-sysread"><code>IO#sysread</code></a>).</p>
</li><li>
<p>Calling <a href="IO.html#method-i-rewind"><code>rewind</code></a> on the stream discards the pushed-back data.</p>
</li></ul>

<p>When argument <code>integer</code> is given, uses only its low-order byte:</p>

<pre class="ruby"><span class="ruby-constant">File</span>.<span class="ruby-identifier">write</span>(<span class="ruby-string">&#39;t.tmp&#39;</span>, <span class="ruby-string">&#39;012&#39;</span>)
<span class="ruby-identifier">f</span> = <span class="ruby-constant">File</span>.<span class="ruby-identifier">open</span>(<span class="ruby-string">&#39;t.tmp&#39;</span>)
<span class="ruby-identifier">f</span>.<span class="ruby-identifier">ungetbyte</span>(<span class="ruby-value">0x41</span>)   <span class="ruby-comment"># =&gt; nil</span>
<span class="ruby-identifier">f</span>.<span class="ruby-identifier">read</span>              <span class="ruby-comment"># =&gt; &quot;A012&quot;</span>
<span class="ruby-identifier">f</span>.<span class="ruby-identifier">rewind</span>
<span class="ruby-identifier">f</span>.<span class="ruby-identifier">ungetbyte</span>(<span class="ruby-value">0x4243</span>) <span class="ruby-comment"># =&gt; nil</span>
<span class="ruby-identifier">f</span>.<span class="ruby-identifier">read</span>              <span class="ruby-comment"># =&gt; &quot;C012&quot;</span>
<span class="ruby-identifier">f</span>.<span class="ruby-identifier">close</span>
</pre>

<p>When argument <code>string</code> is given, uses all bytes:</p>

<pre class="ruby"><span class="ruby-constant">File</span>.<span class="ruby-identifier">write</span>(<span class="ruby-string">&#39;t.tmp&#39;</span>, <span class="ruby-string">&#39;012&#39;</span>)
<span class="ruby-identifier">f</span> = <span class="ruby-constant">File</span>.<span class="ruby-identifier">open</span>(<span class="ruby-string">&#39;t.tmp&#39;</span>)
<span class="ruby-identifier">f</span>.<span class="ruby-identifier">ungetbyte</span>(<span class="ruby-string">&#39;A&#39;</span>)    <span class="ruby-comment"># =&gt; nil</span>
<span class="ruby-identifier">f</span>.<span class="ruby-identifier">read</span>              <span class="ruby-comment"># =&gt; &quot;A012&quot;</span>
<span class="ruby-identifier">f</span>.<span class="ruby-identifier">rewind</span>
<span class="ruby-identifier">f</span>.<span class="ruby-identifier">ungetbyte</span>(<span class="ruby-string">&#39;BCDE&#39;</span>) <span class="ruby-comment"># =&gt; nil</span>
<span class="ruby-identifier">f</span>.<span class="ruby-identifier">read</span>              <span class="ruby-comment"># =&gt; &quot;BCDE012&quot;</span>
<span class="ruby-identifier">f</span>.<span class="ruby-identifier">close</span>
</pre>

                              <div class="method-source-code" id="ungetbyte-source">
            <pre>VALUE
rb_io_ungetbyte(VALUE io, VALUE b)
{
    rb_io_t *fptr;

    GetOpenFile(io, fptr);
    rb_io_check_byte_readable(fptr);
    switch (TYPE(b)) {
      case T_NIL:
        return Qnil;
      case T_FIXNUM:
      case T_BIGNUM: ;
        VALUE v = rb_int_modulo(b, INT2FIX(256));
        unsigned char c = NUM2INT(v) &amp; 0xFF;
        b = rb_str_new((const char *)&amp;c, 1);
        break;
      default:
        SafeStringValue(b);
    }
    io_ungetbyte(b, fptr);
    return Qnil;
}</pre>
                              </div>
                            </div>


                          </div>

                  <div id="method-i-ungetc" class="method-detail ">
                      <div class="method-heading">
                        <span class="method-callseq">
                          ungetc(integer) &rarr; nil
                              </span>
                              <span class="method-click-advice">click to toggle source</span>
                            </div>
                      <div class="method-heading">
                        <span class="method-callseq">
                          ungetc(string)  &rarr; nil
                              </span>
                            </div>

                            <div class="method-description">
                              <p>Pushes back (“unshifts”) the given data onto the stream’s buffer, placing the data so that it is next to be read; returns <code>nil</code>. See <a href="IO.html#class-IO-label-Character+IO">Character IO</a>.</p>

<p>Note that:</p>
<ul><li>
<p>Calling the method has no effect with unbuffered reads (such as <a href="IO.html#method-i-sysread"><code>IO#sysread</code></a>).</p>
</li><li>
<p>Calling <a href="IO.html#method-i-rewind"><code>rewind</code></a> on the stream discards the pushed-back data.</p>
</li></ul>

<p>When argument <code>integer</code> is given, interprets the integer as a character:</p>

<pre class="ruby"><span class="ruby-constant">File</span>.<span class="ruby-identifier">write</span>(<span class="ruby-string">&#39;t.tmp&#39;</span>, <span class="ruby-string">&#39;012&#39;</span>)
<span class="ruby-identifier">f</span> = <span class="ruby-constant">File</span>.<span class="ruby-identifier">open</span>(<span class="ruby-string">&#39;t.tmp&#39;</span>)
<span class="ruby-identifier">f</span>.<span class="ruby-identifier">ungetc</span>(<span class="ruby-value">0x41</span>)     <span class="ruby-comment"># =&gt; nil</span>
<span class="ruby-identifier">f</span>.<span class="ruby-identifier">read</span>             <span class="ruby-comment"># =&gt; &quot;A012&quot;</span>
<span class="ruby-identifier">f</span>.<span class="ruby-identifier">rewind</span>
<span class="ruby-identifier">f</span>.<span class="ruby-identifier">ungetc</span>(<span class="ruby-value">0x0442</span>)   <span class="ruby-comment"># =&gt; nil</span>
<span class="ruby-identifier">f</span>.<span class="ruby-identifier">getc</span>.<span class="ruby-identifier">ord</span>         <span class="ruby-comment"># =&gt; 1090</span>
<span class="ruby-identifier">f</span>.<span class="ruby-identifier">close</span>
</pre>

<p>When argument <code>string</code> is given, uses all characters:</p>

<pre class="ruby"><span class="ruby-constant">File</span>.<span class="ruby-identifier">write</span>(<span class="ruby-string">&#39;t.tmp&#39;</span>, <span class="ruby-string">&#39;012&#39;</span>)
<span class="ruby-identifier">f</span> = <span class="ruby-constant">File</span>.<span class="ruby-identifier">open</span>(<span class="ruby-string">&#39;t.tmp&#39;</span>)
<span class="ruby-identifier">f</span>.<span class="ruby-identifier">ungetc</span>(<span class="ruby-string">&#39;A&#39;</span>)      <span class="ruby-comment"># =&gt; nil</span>
<span class="ruby-identifier">f</span>.<span class="ruby-identifier">read</span>      <span class="ruby-comment"># =&gt; &quot;A012&quot;</span>
<span class="ruby-identifier">f</span>.<span class="ruby-identifier">rewind</span>
<span class="ruby-identifier">f</span>.<span class="ruby-identifier">ungetc</span>(<span class="ruby-string">&quot;\u0442\u0435\u0441\u0442&quot;</span>) <span class="ruby-comment"># =&gt; nil</span>
<span class="ruby-identifier">f</span>.<span class="ruby-identifier">getc</span>.<span class="ruby-identifier">ord</span>      <span class="ruby-comment"># =&gt; 1090</span>
<span class="ruby-identifier">f</span>.<span class="ruby-identifier">getc</span>.<span class="ruby-identifier">ord</span>      <span class="ruby-comment"># =&gt; 1077</span>
<span class="ruby-identifier">f</span>.<span class="ruby-identifier">getc</span>.<span class="ruby-identifier">ord</span>      <span class="ruby-comment"># =&gt; 1089</span>
<span class="ruby-identifier">f</span>.<span class="ruby-identifier">getc</span>.<span class="ruby-identifier">ord</span>      <span class="ruby-comment"># =&gt; 1090</span>
<span class="ruby-identifier">f</span>.<span class="ruby-identifier">close</span>
</pre>

                              <div class="method-source-code" id="ungetc-source">
            <pre>VALUE
rb_io_ungetc(VALUE io, VALUE c)
{
    rb_io_t *fptr;
    long len;

    GetOpenFile(io, fptr);
    rb_io_check_char_readable(fptr);
    if (FIXNUM_P(c)) {
        c = rb_enc_uint_chr(FIX2UINT(c), io_read_encoding(fptr));
    }
    else if (RB_BIGNUM_TYPE_P(c)) {
        c = rb_enc_uint_chr(NUM2UINT(c), io_read_encoding(fptr));
    }
    else {
        SafeStringValue(c);
    }
    if (NEED_READCONV(fptr)) {
        SET_BINARY_MODE(fptr);
        len = RSTRING_LEN(c);
#if SIZEOF_LONG &gt; SIZEOF_INT
        if (len &gt; INT_MAX)
            rb_raise(rb_eIOError, &quot;ungetc failed&quot;);
#endif
        make_readconv(fptr, (int)len);
        if (fptr-&gt;cbuf.capa - fptr-&gt;cbuf.len &lt; len)
            rb_raise(rb_eIOError, &quot;ungetc failed&quot;);
        if (fptr-&gt;cbuf.off &lt; len) {
            MEMMOVE(fptr-&gt;cbuf.ptr+fptr-&gt;cbuf.capa-fptr-&gt;cbuf.len,
                    fptr-&gt;cbuf.ptr+fptr-&gt;cbuf.off,
                    char, fptr-&gt;cbuf.len);
            fptr-&gt;cbuf.off = fptr-&gt;cbuf.capa-fptr-&gt;cbuf.len;
        }
        fptr-&gt;cbuf.off -= (int)len;
        fptr-&gt;cbuf.len += (int)len;
        MEMMOVE(fptr-&gt;cbuf.ptr+fptr-&gt;cbuf.off, RSTRING_PTR(c), char, len);
    }
    else {
        NEED_NEWLINE_DECORATOR_ON_READ_CHECK(fptr);
        io_ungetbyte(c, fptr);
    }
    return Qnil;
}</pre>
                              </div>
                            </div>


                          </div>

                  <div id="method-i-wait" class="method-detail ">
                      <div class="method-heading">
                        <span class="method-callseq">
                          wait(events, timeout) &rarr; event mask, false or nil
                              </span>
                              <span class="method-click-advice">click to toggle source</span>
                            </div>
                      <div class="method-heading">
                        <span class="method-callseq">
                          wait(timeout = nil, mode = :read) &rarr; self, true, or false
                              </span>
                            </div>

                            <div class="method-description">
                              <p>Waits until the <a href="IO.html"><code>IO</code></a> becomes ready for the specified events and returns the subset of events that become ready, or a falsy value when times out.</p>

<p>The events can be a bit mask of <code>IO::READABLE</code>, <code>IO::WRITABLE</code> or <code>IO::PRIORITY</code>.</p>

<p>Returns an event mask (truthy value) immediately when buffered data is available.</p>

<p>Optional parameter <code>mode</code> is one of <code>:read</code>, <code>:write</code>, or <code>:read_write</code>.</p>

                              <div class="method-source-code" id="wait-source">
            <pre>static VALUE
io_wait(int argc, VALUE *argv, VALUE io)
{
    VALUE timeout = Qundef;
    enum rb_io_event events = 0;
    int return_io = 0;

    // The documented signature for this method is actually incorrect.
    // A single timeout is allowed in any position, and multiple symbols can be given.
    // Whether this is intentional or not, I don&#39;t know, and as such I consider this to
    // be a legacy/slow path.
    if (argc != 2 || (RB_SYMBOL_P(argv[0]) || RB_SYMBOL_P(argv[1]))) {
        // We&#39;d prefer to return the actual mask, but this form would return the io itself:
        return_io = 1;

        // Slow/messy path:
        for (int i = 0; i &lt; argc; i += 1) {
            if (RB_SYMBOL_P(argv[i])) {
                events |= wait_mode_sym(argv[i]);
            }
            else if (UNDEF_P(timeout)) {
                rb_time_interval(timeout = argv[i]);
            }
            else {
                rb_raise(rb_eArgError, &quot;timeout given more than once&quot;);
            }
        }

        if (UNDEF_P(timeout)) timeout = Qnil;

        if (events == 0) {
            events = RUBY_IO_READABLE;
        }
    }
    else /* argc == 2 and neither are symbols */ {
        // This is the fast path:
        events = io_event_from_value(argv[0]);
        timeout = argv[1];
    }

    if (events &amp; RUBY_IO_READABLE) {
        rb_io_t *fptr = NULL;
        RB_IO_POINTER(io, fptr);

        if (rb_io_read_pending(fptr)) {
            // This was the original behaviour:
            if (return_io) return Qtrue;
            // New behaviour always returns an event mask:
            else return RB_INT2NUM(RUBY_IO_READABLE);
        }
    }

    return io_wait_event(io, events, timeout, return_io);
}</pre>
                              </div>
                            </div>


                          </div>

                  <div id="method-i-wait_priority" class="method-detail ">
                      <div class="method-heading">
                        <span class="method-callseq">
                          wait_priority          &rarr; truthy or falsy
                              </span>
                              <span class="method-click-advice">click to toggle source</span>
                            </div>
                      <div class="method-heading">
                        <span class="method-callseq">
                          wait_priority(timeout) &rarr; truthy or falsy
                              </span>
                            </div>

                            <div class="method-description">
                              <p>Waits until <a href="IO.html"><code>IO</code></a> is priority and returns a truthy value or a falsy value when times out. Priority data is sent and received using the Socket::MSG_OOB flag and is typically limited to streams.</p>

                              <div class="method-source-code" id="wait_priority-source">
            <pre>static VALUE
io_wait_priority(int argc, VALUE *argv, VALUE io)
{
    rb_io_t *fptr = NULL;

    RB_IO_POINTER(io, fptr);
    rb_io_check_readable(fptr);

    if (rb_io_read_pending(fptr)) return Qtrue;

    rb_check_arity(argc, 0, 1);
    VALUE timeout = argc == 1 ? argv[0] : Qnil;

    return io_wait_event(io, RUBY_IO_PRIORITY, timeout, 1);
}</pre>
                              </div>
                            </div>


                          </div>

                  <div id="method-i-wait_readable" class="method-detail ">
                      <div class="method-heading">
                        <span class="method-callseq">
                          wait_readable          &rarr; truthy or falsy
                              </span>
                              <span class="method-click-advice">click to toggle source</span>
                            </div>
                      <div class="method-heading">
                        <span class="method-callseq">
                          wait_readable(timeout) &rarr; truthy or falsy
                              </span>
                            </div>

                            <div class="method-description">
                              <p>Waits until <a href="IO.html"><code>IO</code></a> is readable and returns a truthy value, or a falsy value when times out.  Returns a truthy value immediately when buffered data is available.</p>

                              <div class="method-source-code" id="wait_readable-source">
            <pre>static VALUE
io_wait_readable(int argc, VALUE *argv, VALUE io)
{
    rb_io_t *fptr;

    RB_IO_POINTER(io, fptr);
    rb_io_check_readable(fptr);

    if (rb_io_read_pending(fptr)) return Qtrue;

    rb_check_arity(argc, 0, 1);
    VALUE timeout = (argc == 1 ? argv[0] : Qnil);

    return io_wait_event(io, RUBY_IO_READABLE, timeout, 1);
}</pre>
                              </div>
                            </div>


                          </div>

                  <div id="method-i-wait_writable" class="method-detail ">
                      <div class="method-heading">
                        <span class="method-callseq">
                          wait_writable          &rarr; truthy or falsy
                              </span>
                              <span class="method-click-advice">click to toggle source</span>
                            </div>
                      <div class="method-heading">
                        <span class="method-callseq">
                          wait_writable(timeout) &rarr; truthy or falsy
                              </span>
                            </div>

                            <div class="method-description">
                              <p>Waits until <a href="IO.html"><code>IO</code></a> is writable and returns a truthy value or a falsy value when times out.</p>

                              <div class="method-source-code" id="wait_writable-source">
            <pre>static VALUE
io_wait_writable(int argc, VALUE *argv, VALUE io)
{
    rb_io_t *fptr;

    RB_IO_POINTER(io, fptr);
    rb_io_check_writable(fptr);

    rb_check_arity(argc, 0, 1);
    VALUE timeout = (argc == 1 ? argv[0] : Qnil);

    return io_wait_event(io, RUBY_IO_WRITABLE, timeout, 1);
}</pre>
                              </div>
                            </div>


                          </div>

                  <div id="method-i-write" class="method-detail ">
                      <div class="method-heading">
                        <span class="method-callseq">
                          write(*objects) &rarr; integer
                              </span>
                              <span class="method-click-advice">click to toggle source</span>
                            </div>

                            <div class="method-description">
                              <p>Writes each of the given <code>objects</code> to <code>self</code>, which must be opened for writing (see <a href="File.html#class-File-label-Access+Modes">Access Modes</a>); returns the total number bytes written; each of <code>objects</code> that is not a string is converted via method <code>to_s</code>:</p>

<pre class="ruby"><span class="ruby-identifier">$stdout</span>.<span class="ruby-identifier">write</span>(<span class="ruby-string">&#39;Hello&#39;</span>, <span class="ruby-string">&#39;, &#39;</span>, <span class="ruby-string">&#39;World!&#39;</span>, <span class="ruby-string">&quot;\n&quot;</span>) <span class="ruby-comment"># =&gt; 14</span>
<span class="ruby-identifier">$stdout</span>.<span class="ruby-identifier">write</span>(<span class="ruby-string">&#39;foo&#39;</span>, <span class="ruby-value">:bar</span>, <span class="ruby-value">2</span>, <span class="ruby-string">&quot;\n&quot;</span>)          <span class="ruby-comment"># =&gt; 8</span>
</pre>

<p>Output:</p>

<pre>Hello, World!
foobar2</pre>

<p>Related: <a href="IO.html#method-i-read"><code>IO#read</code></a>.</p>

                              <div class="method-source-code" id="write-source">
            <pre>static VALUE
io_write_m(int argc, VALUE *argv, VALUE io)
{
    if (argc != 1) {
        return io_writev(argc, argv, io);
    }
    else {
        VALUE str = argv[0];
        return io_write(io, str, 0);
    }
}</pre>
                              </div>
                            </div>


                          </div>

                  <div id="method-i-write_nonblock" class="method-detail ">
                      <div class="method-heading">
                        <span class="method-callseq">
                          write_nonblock(string)   &rarr; integer
                              </span>
                              <span class="method-click-advice">click to toggle source</span>
                            </div>
                      <div class="method-heading">
                        <span class="method-callseq">
                          write_nonblock(string [, options])   &rarr; integer
                              </span>
                            </div>

                            <div class="method-description">
                              <p>Writes the given string to <em>ios</em> using the write(2) system call after O_NONBLOCK is set for the underlying file descriptor.</p>

<p>It returns the number of bytes written.</p>

<p><a href="IO.html#method-i-write_nonblock"><code>write_nonblock</code></a> just calls the write(2) system call. It causes all errors the write(2) system call causes: Errno::EWOULDBLOCK, Errno::EINTR, etc. The result may also be smaller than string.length (partial write). The caller should care such errors and partial write.</p>

<p>If the exception is Errno::EWOULDBLOCK or Errno::EAGAIN, it is extended by <a href="IO/WaitWritable.html"><code>IO::WaitWritable</code></a>. So <a href="IO/WaitWritable.html"><code>IO::WaitWritable</code></a> can be used to rescue the exceptions for retrying write_nonblock.</p>

<pre class="ruby"><span class="ruby-comment"># Creates a pipe.</span>
<span class="ruby-identifier">r</span>, <span class="ruby-identifier">w</span> = <span class="ruby-constant">IO</span>.<span class="ruby-identifier">pipe</span>

<span class="ruby-comment"># write_nonblock writes only 65536 bytes and return 65536.</span>
<span class="ruby-comment"># (The pipe size is 65536 bytes on this environment.)</span>
<span class="ruby-identifier">s</span> = <span class="ruby-string">&quot;a&quot;</span> <span class="ruby-operator">*</span> <span class="ruby-value">100000</span>
<span class="ruby-identifier">p</span> <span class="ruby-identifier">w</span>.<span class="ruby-identifier">write_nonblock</span>(<span class="ruby-identifier">s</span>)     <span class="ruby-comment">#=&gt; 65536</span>

<span class="ruby-comment"># write_nonblock cannot write a byte and raise EWOULDBLOCK (EAGAIN).</span>
<span class="ruby-identifier">p</span> <span class="ruby-identifier">w</span>.<span class="ruby-identifier">write_nonblock</span>(<span class="ruby-string">&quot;b&quot;</span>)   <span class="ruby-comment"># Resource temporarily unavailable (Errno::EAGAIN)</span>
</pre>

<p>If the write buffer is not empty, it is flushed at first.</p>

<p>When <a href="IO.html#method-i-write_nonblock"><code>write_nonblock</code></a> raises an exception kind of <a href="IO/WaitWritable.html"><code>IO::WaitWritable</code></a>, <a href="IO.html#method-i-write_nonblock"><code>write_nonblock</code></a> should not be called until io is writable for avoiding busy loop. This can be done as follows.</p>

<pre class="ruby"><span class="ruby-keyword">begin</span>
  <span class="ruby-identifier">result</span> = <span class="ruby-identifier">io</span>.<span class="ruby-identifier">write_nonblock</span>(<span class="ruby-identifier">string</span>)
<span class="ruby-keyword">rescue</span> <span class="ruby-constant">IO</span><span class="ruby-operator">::</span><span class="ruby-constant">WaitWritable</span>, <span class="ruby-constant">Errno</span><span class="ruby-operator">::</span><span class="ruby-constant">EINTR</span>
  <span class="ruby-constant">IO</span>.<span class="ruby-identifier">select</span>(<span class="ruby-keyword">nil</span>, [<span class="ruby-identifier">io</span>])
  <span class="ruby-keyword">retry</span>
<span class="ruby-keyword">end</span>
</pre>

<p>Note that this doesn’t guarantee to write all data in string. The length written is reported as result and it should be checked later.</p>

<p>On some platforms such as Windows, <a href="IO.html#method-i-write_nonblock"><code>write_nonblock</code></a> is not supported according to the kind of the <a href="IO.html"><code>IO</code></a> object. In such cases, <a href="IO.html#method-i-write_nonblock"><code>write_nonblock</code></a> raises <code>Errno::EBADF</code>.</p>

<p>By specifying a keyword argument <em>exception</em> to <code>false</code>, you can indicate that <a href="IO.html#method-i-write_nonblock"><code>write_nonblock</code></a> should not raise an <a href="IO/WaitWritable.html"><code>IO::WaitWritable</code></a> exception, but return the symbol <code>:wait_writable</code> instead.</p>

                              <div class="method-source-code" id="write_nonblock-source">
            <pre><span class="ruby-comment"># File ruby_3_3_0_preview2/io.rb, line 120</span>
<span class="ruby-keyword">def</span> <span class="ruby-identifier ruby-title">write_nonblock</span>(<span class="ruby-identifier">buf</span>, <span class="ruby-value">exception:</span> <span class="ruby-keyword">true</span>)
  <span class="ruby-constant">Primitive</span>.<span class="ruby-identifier">io_write_nonblock</span>(<span class="ruby-identifier">buf</span>, <span class="ruby-identifier">exception</span>)
<span class="ruby-keyword">end</span></pre>
                              </div>
                            </div>


                          </div>

                          </section>

              </section>
              </main>



            </div>  <!--  class='wrapper hdiv' -->


<footer id="validator-badges" role="contentinfo">
<p><a href="https://validator.w3.org/check/referer">Validate</a></p>
<p>Generated by <a href="https://ruby.github.io/rdoc/">RDoc</a> 6.4.0.</p>
<p>Based on <a href="https://github.com/ged/darkfish/">Darkfish</a> by <a href="http://deveiate.org">Michael Granger</a>.</p>

  
    <p><p><a href="https://ruby-doc.org">Ruby-doc.org</a> is a service of <a href="https://jamesbritt.com">James Britt</a> and <a href="https://neurogami.com">Neurogami</a>, purveyors of fine <a href='https://jamesbritt.bandcamp.com/'>dance noise</a></p>
</p>
  
  </footer>

<script type="text/javascript">


  let ads  = $("#carbonads-container").children().detach();


  function swapMode() {
    var cookieName = 'darkmode';
    var cssDarkmode = Cookies.get(cookieName);
    console.log("***** swapMode! " + cssDarkmode + " *****");


    if (cssDarkmode == "true") {
      console.log("We have dark mode, set the css to light ...");
      $('#rdoccss').attr("href", defaultModeCssHref);
      $('#cssSelect').text("Dark mode");
      cssDarkmode = "false";
      console.log("swapMode! Now set cookie to " + cssDarkmode);
      Cookies.set(cookieName, cssDarkmode);

    } else {
      console.log("We not have dark mode, set the css to dark ...");
      $('#rdoccss').attr("href", darkModeCsseHref);
      $('#cssSelect').text("Light mode");
      cssDarkmode = "true";
      console.log("swapMode! Now set cookie to " + cssDarkmode);
      Cookies.set(cookieName, cssDarkmode);

    }

    console.log("  --------------- ");
  }


const vueCssApp = new Vue({
el: '#menubar',
data: {
isDark: false
},
methods: {
toggleClass: function(event){
this.isDark = !this.isDark;
}
}
})

const vueApp = new Vue({
el: '#vapp',
data: { 
isOpen: true
},

mounted() {
this.handleResize();
this.manage_mob_classes();
window.addEventListener('resize', this.handleResize)
//this.isOpen !=  (/Android|webOS|iPhone|iPad|iPod|BlackBerry|IEMobile|Opera Mini/i.test(navigator.userAgent));
},
destroyed() {
window.removeEventListener('resize', this.handleResize)
},
created() {
//manage_mob_classes();
},

methods : {
isMobile() {
  return (/Android|webOS|iPhone|iPad|iPod|BlackBerry|IEMobile|Opera Mini/i.test(navigator.userAgent));
},

  handleResize() {
    if (!this.isMobile()) {
      this.isOpen = window.innerWidth > 800;
    }
  },

  manage_mob_classes() {
    if (/Android|webOS|iPhone|iPad|iPod|BlackBerry|IEMobile|Opera Mini/i.test(navigator.userAgent)) {
      $("nav").addClass("mob_nav");
      $("main").addClass("mob_main");
      $("#extraz").addClass("mob_extraz");
      $("#carbonads-container").addClass("mob_carbonads-container");
      this.isOpen  = false;
    } else {
      $("nav").removeClass("mob_nav") 
        $("main").removeClass("mob_main");
      $("#extraz").removeClass("mob_extraz");
      $("#carbonads-container").removeClass("mob_carbonads-container");
      this.isOpen  = true;
    }
  },

  toggleNav() {
    this.isOpen =! this.isOpen ;
    // alert("Toggle nav!");
    console.log("toggleNav() click: " + this.isOpen );
  }
}
})

$("#carbonads-container").append(ads);


$(function() {

    var darkmode = Cookies.get("darkmode");
    console.log("Document ready: " + darkmode);

    if ( darkmode  == "true" ) {
      $('#cssSelect').text("Light mode");
    } else {
      $('#cssSelect').text("Dark mode");
     }

    $('body').css('display','block');
    });

</script>

    
  </body> 
</html>

